Genera 8.3 Software Installation Guide for UX Family Machines 



CD-ROM Distribution Media for All Sites 

All sites with Ivory-based machines receive the following CD-ROM distribution 
media: 



Genera 8.3 Distribution Worlds, Sources, and Bundled Products, all 
platforms, 1 CD, P.N. 995854 (This CD contains Genera 8.3 software 
for all machine types, including 3600 Family microcodes, Ivory FEP 
Kernel and Flods, Maclvory Macintosh software, UX UNIX software, 
both Netboot cores, all Distribution worlds, system sources, 
examples, fonts, documentation and loadable systems. In addition, 
the CD contains sources and binaries for the layered products 
Symbolics C, Fortran, and Pascal.) This CD also contains the 
Symbolics Color layered product. Note: You must be under license 
for Symbolics Color in order to restore the Color product. Contact 
your sales representative for more information on the color product. 



Disk Space Requirements for Genera 

Worlds: 

All new machines are shipped from the factory with the most recent version of 
Genera worlds already on disk. 



Ivory: 

Netboot-Core-f rom-Genera-8-3 . i 1 od . 1 

Genera-8-3. ilod. 1 

Genera-8-3-UX-Del ivery . ilod. 1 

Gene ra-8-3-Mac Ivory-Del ivery . ilod. 1 



269 [Netboot core: Genera 8.3] 
44402 [Genera 8.3] 
19325 [Genera 8.3 UX Delivery] 
18367 [Genera 8.3 Maclvory Delivery] 



3600: 

Netboot-Core-f rom-Genera-8-3 . 1 oad . 1 

Genera-8-3. load. 1 



161 [Netboot core: Genera 8.3] 
38367 [Genera 8.3] 



Sources and loadable systems: 

Note that the Genera 8.3 CD-ROM can be used as a SYS host, eliminating the 
need to restore sources and loadable systems to disk. 



• Using the Genera 83 CD-ROM as a SYS host requires only about 260 LMFS 
records (for the SYS:SiTE; directory). 
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• Restoring the Genera 8.3 sources in their entirety requires approximately 41,250 
LMFS records (equivalent to approximately 165,000 Ivory FEP blocks or 204,000 
KBytes for UNIX). 



Overview of CD-ROM Installation 

This section describes the general procedure for installing Genera from CD-ROM. 
Note: In all cases, make sure that machine is powered off before connecting or re- 
moving the CD-ROM drive. 

• Connect the CD-ROM drive to one of the following: 

° An NXP1000 or a Symbolics XL Family machine. See the section "Installing a 
SCSI Device". Symbolics has qualified the Apple CD-ROM drive (Sony model 
CDU-8001) for use with NXPlOOOs and XLs, however, other SCSI CD-ROM 
drives may also work. 

° A Symbolics Maclvory. Follow the manufacturer's instructions for configuring 
and connecting a SCSI CD-ROM drive. 

° A Sun workstation. Follow the manufacturer's instructions for configuring and 
connecting a SCSI CD-ROM device. 

• When the CD-ROM drive is connected to a Sun, you must make the CD-ROM 
drive accessible to other machines on the network. 



Setting up Network Access for a CD-ROM Drive on a Sun Workstation 

1. Check the UNIX permissions on /dev/srB. These permissions will be propagat- 
ed by SunOS to all files on the Genera Distribution CD-ROM. At a minimum, 
the read and execute bits must be set for the user who will perform the in- 
stallation (often root). For more information on setting UNIX file permissions, 
see the SunOS Reference Manual entry for chmod. For more information on 
the Sun CD-ROM driver, see the SunOS Reference Manual entry on sr. 

2. Insert the CD-ROM in the Sun CD-ROM drive, and turn on the drive. Mount 
the CD-ROM into the Sun filesystem using the UNIX mount command (the 
mount command must be run by the super-user): 

% su 

# mount -o ro -t hsfs /dev/srB /cdrom 

For more information on the UNIX mount command, see the SunOS Reference 
Manual entry on mount. 
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3. On the machine with the CD-ROM drive, make sure that the directory the 
CD-ROM is mounted onto is exported (see the SunOS Reference Manual entry 
on exportfs). 



CD-ROM Installation Steps - an Overview 

1. (Sites with Maclvories only) 

Install the Genera 8.3 Maclvory Macintosh software on all Maclvories which 
will run Genera 8.3. Since installing this software from CD-ROM requires a 
CD-ROM drive on the local Maclvory, we suggest that you install this from 
the Genera 8.3 Maclvory floppies. See the section "Installing the Maclvory 
Diskettes". 

2. (Sites with UX Family machines only) 

Install the Genera 8.3 UX UNIX software on all UX Family machines which 
will run Genera 8.3. Run the UX UNIX software installation tool, to install 
the Genera 8.3 UX UNIX software from the tape. See the section "Upgrading 
the Symbolics UX UNIX Software". 

3. Restore the Genera 8.3 Distribution worlds from CD-ROM, see the section 
"Restoring the Genera Distribution Worlds From CD-ROM". 

4. Make a site-configured Genera 8.3 world for each machine-type. See the sec- 
tion "Making a Genera Site-Configured World". 

If your CD-ROM drive is connected to a Maclvory or an XL running Genera 
8.3, it is possible to use the CD-ROM as a sys host. If you wish to store any 
portion of the Genera 8.3 documentation, sources, examples, fonts, and non- 
loaded systems on CD-ROM instead of in a LMFS, See the section "Using a 
CD-ROM as a SYS Host" and use that section as a guide when updating your 
sys.translations file. 

5. If there are any Genera 8.3 documentation, sources, examples, fonts, or non- 
loaded systems that you do not plan to access from CD-ROM, you must re- 
store them into a Lisp Machine File System (LMFS) or a UNIX File System. 
For instructions on how to do this, see the section "Restoring the Genera 
Sources". 

6. On each machine that is now running a site-configured Genera 8.3 world, 
copy the new flod files. See the section "Copying New Flod Files" for each 
machine type. Note: The Flod files for 3600-family machines are the same as 
in previous Genera releases. Therefore, this step is not necessary on 3600- 
family machines. 

7. Cold boot each machine with the new flods. 
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8. Make customized user and server worlds for your site. See the section "Mak- 
ing Customized Genera User and Server Worlds". 

9. Back up your world(s) to tape. See the section "Backing Up Worlds to Tape". 



Upgrading the Symbolics UX UNIX Software 

Upgrading the Symbolics UX UNIX Software for a new release of Genera is subtly 
different from installing a new UX system. For more information on UX installa- 
tion, use the online documentation for the Genera 8.1 Software Installation Guide. 

If the Sun CD-ROM is not connected to the machine on which the UX UNIX soft- 
ware is to be installed, the CD-ROM must be mounted onto the UX machine's 
filesystem. On the machine with the CD-ROM drive, make sure that the directory 
the CD-ROM is mounted onto is exported (see the SunOS Reference Manual entry 
on exportfs). On the machine on which the UX UNIX software is to be installed, 
mount the CD-ROM onto the filesystem: 

% su 

# mkdi r /cdrom 

# mount OtherSun: /cdrom /cdrom 

In order to upgrade the Symbolics UX UNIX Software, follow the installation pro- 
cedure described in Installing and Configuring the Symbolics UX UNIX Software, 
but answer No to the questions in'Thase 4 (FEP Partition File Configuration) of 
Symbolics UX Installer Program" and some of the questions in "Phase 5 (UNIX 
Startup Configuration) of Symbolics UX Installer Program". 

More specifically, the usual "Phase 5 (UNIX Startup Configuration) of Symbolics 
UX Installer Program" answers for an upgrade will be as follows: 

Do you wish to install the UX400S/UX1200S kernel? 

Yes . Upgrading the UX UNIX software requires building a new UNIX 
kernel which will include the new release of the UX device drivers. 
This question controls whether the new kernel will be installed (the 
kernel is actually built in Phase 3). 

Do you wish to create the UX400S/UX1200S configuration file(s)? 

No . The UX configuration files only need to be updated in order to add 
or remove network interfaces of FEP partition files, or to change the 
directory where IFEP PROM files are stored, or when a new UX board is 
being installed. Upgrading the UX UNIX software doesn't usually involve 
any of these situations. 

Do you wish to create/update the UX400S/UX1200S device files in /dev? 

Yes . The UX device files should be updated whenever a new UNIX kernel 
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is built, in order that they specify the correct major device number for 
the UX device driver. 

Do you wish /etc/rc. local to start UX400S/UX1200S life support? 

No. /etc/rc. local only needs to be updated when a new UX board is added 
to the system. 

Do you wish to reboot UNIX after installation? 

Yes . UNIX should be rebooted whenever a new kernel is installed. 
A sample upgrade dialogue would look something like the following. 

% su 

Password: 

# cd /cdrom/sun 

# extract_cdrom 

The following product will be installed: 
Symbolics UX400S/UX1200S UNIX Software for SunOS 4.1.2, Genera 8.3 

Copyright (c) 1993 Symbolics, Inc. All rights reserved. 
Portions of font library Copyright (c) 1984 Bitstream, Inc. 
All Rights Reserved. 

TRADEMARK NOTICE 

Symbolics, Ivory, Symbolics UX400S, and Symbolics UX1200S are trademarks 
and Genera is a registered trademark of Symbolics, Inc. 

UNIX(R) is a registered trademark of AT&T. X Window System is a 
trademark of the Massachusetts Institute of Technology. Open Windows, 
Sun, Sun-3, Sun-4, and SunOS are trademarks, and Sun Microsystems is 
a registered trademark of Sun Microsystems, Inc. 

Use the Genera Show Legal Notice command to see important legal notices. 

Do you want to continue [y|n]? y 

Do you wish to restore UX-family sun3 life support? y 

Do you wish to restore UX-family life support sources? y 

Do you wish to restore the Genera fonts? y 
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extract_cdro:m Restoring files 

x ./sun3/etc/test-ivory, 139264 bytes, 272 tape blocks 

x ./ifep/solstice-device.prom, 130717 bytes, 256 tape blocks 

x ./src/Makefile, 58127 bytes, 114 tape blocks 

x ./src/autoboot.c, 4193 bytes, 9 tape blocks 

[many other files here ...] 

extract_cdrom: Running installation tool 

Do you wish to install the UX400S/UX1200S software (default Yes)? 

The ivory-life program has to be run by root, the super-user. 

Do you wish ivory-life to be installed setuid to root (default Yes)? 

Certain services provided by the ivory-servicesd program require that it run as root. 

Do you wish ivory-servicesd to be installed setuid to root (default Yes)? 

Several of the UX400S/UX1200S life-support programs want to be able to read /dev/kmem. 

Do you wish these programs to be installed setgid to kmem (default Yes)? 

Where should application programs go (default /usr/bin)? 

Where should maintenance and installation programs go (default /usr/etc)? 

Where should include files go (default /usr/include/ivory)? 

Where should libraries go (default /usr/lib)? 

Do you wish to install sources to the UX400S/UX1200S software (default Yes)? 

Where should sources go (default /usr/share/symbol ics/src)? 

Where should IFEP proms go (default /usr/share/symbol ics/ifep)? 

Do you wish to install the Genera fonts for the Sun Open Windows X server (default Yes)? 

Where do the Open Windows programs live (default /usr/openwin)? 

Where should the Open Windows Genera fonts go (default /usr/openwin/1 ib/genera-fonts)? 

WARNING: directory /usr/openwin/1 ib/genera-fonts is not in the search 
path defined by environment variable FONTPATH. Make sure to update 
FONTPATH to to include /usr/openwin/1 ib/genera-fonts. 



Do you wish to install the Genera fonts for the MIT X server (default No)? 

Do you wish to build a UNIX kernel with support for the UX400S/UX1200S (default Yes)? 

How many UX400S boards should this kernel support (default 1)? 

How many UX1200S boards should this kernel support (default 1)? 

Where is your kernel build directory (default /usr/share/sys)? 

What kernel architecture does this machine use (default sun3)? 

What kernel usually runs on this machine (default GENERIC)? 

Do you wish to create FEP partition file(s) (default Yes)? no 

Do you wish to install the UX400S/UX1200S kernel (default Yes)? yes 

Do you wish to create the UX400S/UX1200S configuration file(s) (default Yes)? no 

Do you wish to create/update the UX400S/UX1200S device files in /dev (default Yes)? yes 
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Do you wish /etc/rc. local to start UX400S/UX1200S life support (default Yes)? no 
Do you wish to reboot UNIX after installation (default Yes)? yes 

About to begin UX400S/UX1200S software installation, this will probably take a while. 
Okay (default Yes)? 



Restoring the Genera Distribution Worlds From CD-ROM 

Note: CD-ROM installation only works properly in Genera 8.1.1 or later versions. 
Be sure to install the Genera 8.3 worlds using a machine running Genera 8.1.1. or 
later. 

Restore the Genera 8.3 world load files into your FEP file system, using the CD- 
ROM labeled GENERA 8.3 DISTRIBUTION WORLDS, SOURCES, AND BUNDLED PRODUCTS. 

1. Insert the Genera 8.3 CD-ROM into the CD-ROM drive at your site. Type the 
CP command Select Activity FEP-Tape. In the FEP-Tape activity, type the 
command: 

Read Image File 

We recommend that you type this command, rather than choose it from the 
FEP Tape menu, because the typed command gives you more control over the 
tape specification. Supply the pathname of a tape image on the Genera 8.3 
CD-ROM according to the following: 

CD-ROM drive on a Lisp machine 

Lisp-host | CDROMn:>DISTRI BUT 1 0N>BASIC_W0RLD. TAPE 

CD-ROM drive on a Sun 

Sun-host : /cdrom/di stri buti on/basi c_worl d . tape 

where "n" is the SCSI address of the ROM Drive. 

2. On Ivory-based machines, you are asked if you want to restore the FEP ker- 
nel and flod files. Answer Y (for Yes) and accept the default pathname. 

Note: Do not delete your old FEP kernel and flod files. We recommend that 
you always save the previous version of the kernel and flod files for a backup. 
See the section "Saving Previous FEP Kernels and FLOD Files". 

3. You are asked if you want to restore the Genera 8.3 Netboot Core. Answer Y 
(for Yes) and accept the default pathname. 

4. You are asked if you want to restore the Genera 8.3 world load file. Answer Y 
(for Yes) and accept the default pathname, or specify a FEP pathname that 
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indicates an Ivory world load, such as: 
FEP0:>Genera-8-3.ilod 

The FEP-Tape loading program then loads the world from the CD-ROM. 

5. Update the boot . boot file on your machine to load the new world. Your up- 
dated boot . boot file should look similar to this: 

Load World 
Start 

This automatically loads the most recently created world on your disk (exclud- 
ing netboot cores). Note: The next time you boot your machine, you must cold 
boot the FEP in order to use the new FEP kernel and FLOD files. 

See the section "Contents of Hello. Boot Files and Boot.Boot Files". 

6. For the remaining Genera 8.3 distribution worlds, use the Copy File command 
to copy the appropriate Genera worlds from the "worlds" directory on the CD- 
ROM to your local FEP filesystem. 

If the CD-ROM drive is connected to an NXP1000, XL or a Maclvory, the 
world pathnames will look similar to this (where host is the name of the CD- 
ROM host, and n in CDROMn is the SCSI address of the CD-ROM drive): 

cdrom-host | CDROMn : >W0RLDS>GENERA_8_3 . 1 LOD 

If the CD-ROM drive is connected to a Sun workstation, the world pathnames 
will look similar to this (where host is the name of the Sun CD-ROM host, 
and Icdrom is the directory the CD-ROM is mounted onto. 

cdrom-host: i 'cdrom/vior~\ ds/genera_8_3 . 1 oad 

Note: The ISO9660 pathnames on the CD-ROM contain underscores which 
should be changed to hyphens when you copy the files to your FEP. 

For example, when copying the Genera 8.3 world from CD-ROM to a 3600, 
with the CD-ROM drive connected to a Sun, you would type the following to a 
Lisp Listener (where 3600-host is the name of the 3600): 

Copy File cdro/n-/ios£:/cdrom/worlds/genera_8_3.1oad 3600-host | FEP0:>genera-8-3.1oad 

Similarly, with the CD-ROM drive, SCSI address 3, connected to a Maclvory 
or XL, you would type the following: 

Copy File CDflOM-iTOST I CDR0M3:>W0RLDS>GENERA_8_3. LOAD (to) 
3600-host | FEP0 : >genera-8-3 . 1 oad 

The worlds directory on the CD-ROM contains the following worlds: 
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GENERA_8_3.IL0D 
GENERA_8_3.L0AD 
GENERA_8_3_MACI_DELIUERY.IL0D 
GENERA_8_3_UX_DEL I VERY . I LOD 
NETB00T_C0RE_GENERA_8_3 . I LOD 
NETBOOT CORE GENERA 8 3. LOAD 



Completing the Installation 



Creating a New Site for Genera 



The steps in this section should be performed at new sites that have multiple Sym- 
bolics (3600-family, Maclvory, XL, NXP, or UX) machines. 



Choosing Names, Addresses, and Servers for the New Site 

1. Select a name for the site. For information about choosing site names, see the 
section "Choosing a Site Name". 

2. Select a name for each machine at the site, including non-Symbolics ma- 
chines. 

3. Select a network address for each Symbolics computer. Symbolics UX ma- 
chines must have both a Chaosnet address and an Internet address. 

Remember that each machine must have a unique network address. Machines 
that are not Symbolics computers might already have Internet addresses for 
IP-TCP networks. If not, select the appropriate network addresses for them. 
For information about network addresses, see the section "Choosing Machine 
Names and Network Addresses". 

Note: All preconfigured machines come from Symbolics with Chaosnet address 
52525. Unless you have a standalone machine, this is not a desirable Chaosnet 
address. 

4. Choose a Symbolics computer to be your namespace server. You cannot use a 
non-Symbolics machine for a namespace server. For information about server 
machines, see the section "Machines and Worlds". 

5. Choose a machine to be the file server and, if necessary, the print server, 
mail server, and Domain server. Symbolics recommends that you use your 
namespace server machine for these, provided it has enough disk space. More 
information is available about choosing server machines. See the section "Ma- 
chines and Worlds". 
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Contents of Hello.Boot Files and Boot.Boot Files 

This section briefly describes the philosophy of which FEP commands belong in 
the Hello. boot file and which belong in the Boot. boot file on both 3600-family and 
Ivory-based machines. 

Hello. boot File 

This file should contain anything that holds constant for this machine, regardless 
of the world you are running. For example, this includes your flod files, your pag- 
ing files, your network address, and so on. 

First, this file must scan all the flods from which you want to use commands. This 
includes the lisp, loaders, info, and debug flods. 

Next, the file should include the Initialize Hardware Tables command, so that any 
errors it encounters will be seen early in the booting process. (This command is 
completely optional in Ivory-based machines. It is automatically invoked by the 
Ivory FEP when needed, but errors it signals may be less clear when automatically 
invoked.) 

Then, the Hello. boot file should declare any paging files you always want to use; 
this saves you having to manually Add Paging Files, or to say the same in your 
boot file. Do not declare any "spare" paging you want to save for an emergency, 
because Load World automatically uses all declared paging files, and thus the 
spare paging file would not be available in case of an emergency. It is harmless to 
declare paging files that do not exist (for example, one you might delete every now 
and then to make room for Copy World); nonexistent ones give a warning, but are 
not used. 

Ivory machines only: 

Starting with Genera 8.1, the hello. boot file for an Ivory machine should contain 
two lines: 

Hello Innn 

Hel 1 o Local (or hostname) 

Each of these corresponds to a boot file. The nnn refers to the IFEP number, 
which is 328 for Genera 8.3. 



Hello Innn Boot File 

The Innn.boot file (where nnn is the IFep version number, which is 328 for Gen- 
era 8.3) should contain the commands to scan the flod files and initialize things. 

Scan 1328-1 isp. flod 
Scan 1328-1 oaders. flod 
Scan 1328-info. flod 
Scan 1328-debug. flod 
Initialize Hardware Tables 
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Hello Local Boot File 

The local. boot file should contain those commands that set up this specific ma- 
chine, declaring paging files, setting the network address, and any other boot op- 
tions. 

Declare Paging Files FEP0:>Paging-1 .page 

Declare More Paging Files FEP0:>Paging-2. page, Paging-3. page 

Set Boot Options :Network Address Chaos|52525 : I DS Enable 



Boot options are required for standalone sites. They are optional for other sites, 
but they do save manually invoking them or having them duplicated or inconsis- 
tent in boot files (if you have multiple boot files). See the section "Set Boot Op- 
tions FEP Command". 

The boot options replace other FEP commands. For compatibility, some of the boot 
options have corresponding commands. Note that some of these commands (such as 
Enable/Disable IDS on 3600-family machines), if present, must appear in the 
Boot . boot file, since they must follow Load World. (In the Ivory-based FEP, these 
commands warn if you try to use them at the wrong time, while in the 3600-family 
FEP they silently perform no operation if used at the wrong time). We recommend 
using the Set Boot Options command instead of the corresponding commands, so 
you can set all the boot options in one spot. 

Normally, you set your network address with Set Boot Options, but you could use 
the Set Network Address command instead. Whichever way you choose to set the 
network address, it should be done in the Local . boot file, and should not be dupli- 
cated in your Boot . boot files. 

3600 and Ivory Machines 

Note that, in previous releases, you had to set the network address after loading 
the world, but this restriction no longer holds on either architecture. 

Here is a sample Hello. boot file for a 3600-family machine: 



Sample 3600-Family Machine Hello.Boot File 

Scan v127-info. flod 

Scan V1 27-1 oaders. flod 

Scan v127-l isp. flod 

Scan v127-debug. flod 

Initialize Hardware Tables 

Declare Paging-Files FEP0:>Paging-1 .page 

Declare More Paging-Files FEP0:>Paging-2. page, Paging-3. page 

Set Chaos-Address 52525 

(For a sample Hello. boot file for an Ivory-based machine, see the section "Sample 
Ivory-Based Machine Hello.Boot File".) 
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Boot. boot Files 

These files should contain any setting that pertains only to the particular world 
(and microcode, on a 3600-family machine) this file loads and starts. (Note that 
this excludes the address of the machine.) There is a slim possibility that you 
might want to have some explicit paging file commands here (for example, a boot 
file to boot with just one paging file explicitly added for when you want to do 
world copying). 



Sample 3600-Family Boot.Boot Files 

Here is the sequence of commands for a Symbolics 3600-family machine that is 
cold booting a world from the local disk: 

Clear Machine 

Load Microcode FEP0:>3640-f pa-mi c. mi c. 430 

Load World FEP0:>genera-8-3. load 

Enable IDS 

Start 

Here is the sequence of commands for a Symbolics 3600-family machine that is 
cold booting a world from a remote disk (netbooting): 

Clear Machine 

Load Microcode FEP0:>3640-fpa-mic.mic.430 

Netboot inc-site-genera-8-3 

Enable IDS 

Start 

The information in the rest of this section applies to Ivory-based machines only. 

Boot . boot files for Ivory-based machines should contain only the following: 

Load World 
Start 

Note that you can set your default world to boot in boot options. If you choose to 
load the default world, there is no need to give an explicit pathname argument to 
Load World. 

It is unnecessary to do a Clear Machine before the Load World since this com- 
mand does nothing on Ivory-based machines. On 3600 family machines, it serves a 
purpose. To avoid confusion and make boot files easier to understand and main- 
tain, if Clear Machine is left in the boot file of an Ivory machine, it is ignored. 

It is possible, although not recommended, to give the Enable/Disable IDS command 
here, but the recommended way is to do all that in your Hello. boot file, via Set 
Boot Options :IDS [Enable/Disable]. You should also use the Set Network Address 
commands in your Hello. boot file. (Note that if someone copies a boot file with an 
address in it to another machine, confusion will result.) 

Note also that Disable IDS saves only an inconsequential amount of memory and 
overhead, so there is usually no advantage in doing it. 



Page 689 



Here is the recommended sequence of commands for a Symbolics Ivory-based ma- 
chine that is cold booting a world from the local disk: 

Load World 
Start 

This loads the most recent world on your local disk, which is usually the one you 
want to boot. 

For a netbooted machine, the recommended sequence is: 

Netboot inc-site-genera-8-3 
Start 



At this point you are ready to boot Genera. 



Defining the New Site 

This step should be performed at new sites with multiple machines only. Sites 
with a standalone XL or a standalone Maclvory do not need to define a site. 

On the namespace server machine, use the Define Site command to create the ini- 
tial namespace database. Once you have entered data into this database, the name- 
space files are stored permanently. 

Define Site enables the local machine to access the permanent namespace database 
files, and at the same time, it creates a host namespace object for the local ma- 
chine. 



Define Site Dialogue for XL, 3600, and Maclvory Machines 

In a Lisp Listener, issue the Define Site command and give a site name. This 
might be the name of your company, or it can be related to the machine names 
you have chosen. 

Command: Define Site (site name) Downunder 
A menu comes up with with the necessary fields to be filled in, as in Figure 59 : 

Connand: Define Site (site nane) Doununder 

Defining site DOWNUNDER with the local host as the Primary Nanespace Server 

Nanespace Server Nane: the nsne of the prinsry ns.nesps.ce server 

< abort > aborts^ <1S1> uses these values 



Figure 61. The basic Define Site menu 



Enter the name of your namespace server. The Define Site dialogue expects an ac- 
tual name here, so do not enter Local for the Namespace Server name. 
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After you have entered the name of your namespace server, additional menu slots 
are displayed, with the appropriate default information filled in. You can, of 
course, change them. 

Connand: Define Site (site nane) doununder 

Defining site DOWNUNDER with the local host as the Primary Nanespace Server 

Nanespace Server Nane: uonbat 

System File Directory: uonbat : >sys>si te> 

Nanespace Descriptor File: uonbat : >sys>si te>DOWNUNDER-nanespace . text 

Default Login: Li sp-Nachi ne 

Host for Bug Reports: uonbat 

Local Tinezone: EDT 

Standalone Site: Yes No 

< abort > aborts^ <1S1> uses these values 



Figure 62. An expanded Define Site menu 



Namespace Server Name 

The name of the local host in the new site. 

System File Directory 

The physical directory that will correspond to the logical direc- 
tory SYS:SiTE; in the new site. For more information, see the 
section "Logical Pathnames and the SYS Host". 

Namespace Descriptor File 

The name of the file that will hold the namespace description 
that is used to find all the files that make up the namespace 
database. 

Default Login The "Lispm name" of the user object "Lisp-Machine". 

Host for Bug Reports 

The name of the host that will accept bug-report mail. For in- 
formation about the mailer, see the section "Installing and 
Configuring the Mailer". 

Local Timezone The abbreviation of the local timezone or an integer indicating 
the hour offset from GMT. For more information about time 
zones, see the section "Specifying a Time Zone for Your Site". 

Standalone Site Whether the local site consists of just the local machine or 
not. A broadcast is used to verify the identity of the local host 
and get the current time when booting at non-standalone sites. 
Saying "Yes" means that these broadcasts will not be per- 
formed. 

Press END to define your site. 
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Now you are ready to add your machines to your site. 
Registering a New Symbolics XL, Maclvory Machine, or 3600 

Choosing a Name and Network Address for the New Machine 

Select a name and network address(es) for the new machine. Symbolics UX ma- 
chines must have both a Chaosnet address and an Internet address. For informa- 
tion about network addresses, see the section "Choosing Machine Names and Net- 
work Addresses". 

Note: All preconfigured machines come from Symbolics with Chaosnet address 
52525. Unless you have a standalone machine, this is not a desirable Chaosnet ad- 
dress. 

Creating a New Host Object for a 3600, XL, or Maclvory Machine 

1. Use the Namespace Editor on the namespace server to set up the namespace. 
For information about using the Namespace Editor, see the section "Using 
the Namespace Editor". 

2. Create a host object for each new 3600-family, XL, and Maclvory machine at 
the site. The system type for all machines is "Lispm". The machine type 
should be one of "3600", "XL400", "XL1200", or "Maclvory". Supply the appro- 
priate Chaosnet address for each machine. 

3. Create namespace objects that represent users, other computers and printers 
at the site (whether Symbolics or non-Symbolics machines). 



Making a Genera Site-Configured World 

Note: You must build a site-configured world for each machine type (3600-Family 
or Ivory) at your site, with the exception of standalone sites that consist of only 
one Maclvory or one XL machine. We do not recommend saving a site-configured 
world in which the Define Site command has been issued. When building a site- 
configured world, use the Set Site command on a freshly booted machine. 

Perform these steps to make a site-configured world: 

1. Edit (update) the sys:SITE;SYS.translations file. For instructions on how to do 
this, see the section "Updating the Sys. Translations File for Genera 8.3". 

Once you have updated the translations file, return to this section and finish 
making the Genera 8.3 site-configured world. 

2. Cold boot the Genera 8.3 distribution world on your machine. 
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3. Use the Set Site command to configure the machine for your site. For infor- 
mation about the Set Site dialogue, see the section "Set Site Dialogue". 

4. Save the new world, using either the Save World Complete command or the 
Save World Incremental command, depending on your circumstances. Informa- 
tion is available to help you make this decision. See the section "Save World 
Command". 

This example shows how to save an incremental version of the world for Gen- 
era 8.3 on Ivory-based machines: 



Save World Incremental FEP0:>Inc-Site-f rom-Genera-8-3. load 

This site-configured world will serve as the base world for all Ivory worlds 
you build at your site, except for the namespace server's world. Similarly, a 
site-configured 3600 world will serve for all 3600-Family worlds you build at 
your site (except for namespace server worlds). Information is available about 
making user and server worlds for your site. See the section "Making Cus- 
tomized Genera User and Server Worlds". 



Updating the Sys.Translations File for Genera 8.3 

Before making a site-configured world, edit the file syS:SitE;SYS.translations so 
that Genera 8.3 will "know" where its sources reside. Once you have finished edit- 
ing the sys.translations file for your site, save and load the file. 

Symbolics suggests that you use a Symbolics NXP1000, XL, Maclvory, or 3600 
Family machine to hold the distribution sources. Alternatively, you can use a non- 
Symbolics machine to store sources. For further information, see the section "Stor- 
ing Genera Sources on a Non-Symbolics Machine". 

For sites that use NXP, Maclvory, XL, or 3600-series machines, it is preferable to 
store sources on NXP, XL, or 3600-series machines, rather than Maclvories. 

If the machines at your site will be running only Genera 8.3, use this example as 
a model for your SYS.TRANSLATIONS file: 

;;; -*- Mode: LISP; Syntax: Common-lisp; Package: USER -*- 
(fs: set-logical -pathname-host "SYS" translations 
' ( " sys : xx ; x . x . x" " ACME-SMBX : >rel -8-3>sys>xx>x .*.*")) 

If the machines at your site will be running multiple versions of Genera, see the 
section "A Sample SYS.TRANSLATIONS File That Stores Genera Sources for Mul- 
tiple Releases". 



A Sample SYS.TRANSLATIONS File That Stores Genera Sources for Multiple 
Releases 
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This example shows a sys.translations file that has been conditionalized to allow 
Genera 8.1.1, and Genera 8.2 NXP to coexist with Genera 8.3. In this example, 
ACME-SMBX is the name of the Symbolics computer on whose Lisp Machine File Sys- 
tem (LMFS) the sources will be stored. 

;;; -*- Mode: LISP; Syntax: Common-lisp; Package: USER -*- 
(multiple-value-bind (major-version minor-version) 
(set : get- r el ease-versi on) 
(select major-version 

;; Translations for Genera 8.1.1, 8.2 NXP, and 8.3 
(8 (selector minor-version equalp 
(("1.1") 
(fs: set-logical -pathname-host "SYS" [translations 

' ( (" sys : xx; x . x . x" "ACME-SMBX : >rel -8-1 >sys>xx>x .*.*")))) 
(("2 NXP" "2.1 NXP") 
(fs: set-logical -pathname-host "SYS" [translations 

' ( ( " sys : xx ; x . x . x" " ACME-SMBX : >rel -8-2>sys>xx>x .*.*")))) 
((3) 
(fs: set-logical -pathname-host "SYS" [translations 

' ( ( " sys : xx ; x . x . x" " ACME-SMBX : >rel -8-3>sys>xx>x .*.*")))) 
(otherwise (error "~A ~A unknown release or system version. ~2T 

Edit SYS:SITE;SYS. TRANSLATIONS to add this system, 
major-version minor-version)))) 
(otherwise (error "~A ~A unknown release or system version. ~2T 

Edit SYS:SITE;SYS. TRANSLATIONS to add this system, 
major-version minor-version)))) 



Managing System Source Files When Running Multiple Releases 

If you are planning to run more than one release at the same time, we recommend 
keeping sources for all of them. Keeping all sources available may not be possible 
because of disk space limitations on your SYS host (or hosts), but the lack of cer- 
tain source files may cause problems. This means that if you wish to delete some 
of the Genera 8.3 sources, you may have to employ a workaround. 

The workaround is to change the sys.translations file so that Genera 8.1 and 8.2 
can find files in the Genera 8.3 directory. This workaround is limited to Genera 
fonts, and FEP flod file directories. Do not use the workaround on documentation, 
X-fonts, Lisp sources, or binaries. 

For example, if you have to delete the Genera 8.3 font files from your SYS host, 
modify the translations file as shown in bold (this translation allows users of Gen- 
era 8.1 and 8.2 systems to find screen fonts in the >rel-8-3> directory. 
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;;; -*- Mode: LISP; Syntax: Common-lisp; Package: USER -*- 
(multiple-value-bind (major-version minor-version) 
(set : get- r el ease-versi on) 
(select major-version 

;; Translations for Genera 8.1.1, 8.2 NXP, and 8.3 
(8 (selector minor-version equalp 
(("1.1") 
(fs: set-logical -pathname-host "SYS" translations 
' (("sysrfonts;**;*.*.*" 

"ACME-SMBX:>rel-8-3>sys>fonts>**>*.*.*") 
(" sys : xx; x . x . x" " ACME-SMBX : >rel -8-1 >sys>xx>x .*.*")))) 
(("2 NXP" "2.1 NXP") 
(fs: set-logical -pathname-host "SYS" [translations 
' (("sysrfonts;**;*.*.*" 

"ACME-SMBX:>rel-8-3>sys>fonts>**>*.*.*") 
( " sys : xx ; x . x . x" " ACME-SMBX : >rel -8-2>sys>xx>x . x . x" ) ) ) ) 
((3) 
(fs: set-logical -pathname-host "SYS" translations 

' ( ( " sys : xx ; x . x . x" " ACME-SMBX : >rel -8-3>sys>xx>x .*.*")))) 
(otherwise (error "~A ~A unknown release or system version. ~2T 

Edit SYS:SITE;SYS. TRANSLATIONS to add this system, 
major-version minor-version)))) 
(otherwise (error "~A ~A unknown release or system version. ~2T 

Edit SYS:SITE;SYS. TRANSLATIONS to add this system, 
major-version minor-version)))) 

If you are using a non-Symbolics machine to store your system documentation, 
sources, examples, fonts, and non-loaded systems, you would make such a modifica- 
tion in the appropriate file system syntax. 

Once you have made a site-configured world, you are ready to restore the Genera 
8.3 documentation, sources, examples, fonts, and non-loaded systems. 



Restoring the Genera Sources 

This section describes how to restore the Genera documentation, sources, exam- 
ples, fonts, and non-loaded systems. This step is not necessary for sites that use 
the CD-ROM as a sys host. See the section "Using a CD-ROM as a SYS Host". 

Use the CD-ROM labeled Genera 8.3 Distribution Worlds, Sources, and Bundled 
Products. 

Restoring the Genera sources in their entirety requires approximately 41,250 
LMFS records (equivalent to approximately 165,000 FEP blocks or 204,000 KBytes 
for UNIX). If you have limited disk space (for example, if you have only one ma- 
chine at your site), you may want to restore the sources selectively, to conserve 
disk space. 

You can use a non-Symbolics machine to store the Genera documentation, sources, 
examples, fonts, and non-loaded systems. For information on how to do this, see 
the section "Storing Genera Sources on a Non-Symbolics Machine". 
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1. Boot the a site-configured Genera world and put the Genera 8.3 CD-ROM into 
the CD-ROM drive. 

2. Use the following command to restore the files from the distribution image 
on the CD-ROM: 

Restore Distribution :Menu yes :Use Disk yes 

The system responds by displaying a menu, as shown in Figure 47. 



Restore Distribution 



Help 

Initialize Restoration 



Perform Restoration 



Skip restoration of files that already exist: 

Yas No 
Write informational output to: 

Standard-Output a destination 
Read distribution from device: 
Tape Disk 
Spec for tape: 

Local: SCSI1 , den=1 600 



| Systems to Restore 
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MACRO-CALLS-DATABASE 
TV-FONTS 
IFEP-DISTRIBUTION 
STANDALONE-SITE-FILES 
NFEP-OVERLAYS 
MICROCODES 
SYSTEM 
CLOS 

DEVELOPMENT-UTILITIES 
OLD-TV 
UTILITIES 
SERVER-UTILITIES 
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stem LEGAL-NOTICE: 

SITE;NOTICE. TEXT. 100 
stem MACRO-CALLS-DATABASE: 

PATCH;SYSTEM-436;MACRO-CALLS.BIN.3 
PATCH;SYSTEM-436;MACRO-CALLS.IBIN.5 
stem TV-FONTS: 
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Figure 63. System Selection Menu for the Restore Distribution Command 

In the restore distribution frame, specify a pathname for a distribution image 
on the CD-ROM from the following list: 

8_3_S0URCE_DIST_1 .TAPE ; Genera sources and documentation 
8_3_S0URCE_DIST_2.TAPE ; Genera non-loaded systems 

8_3_FPC_DIST.TAPE ; Symbolics Fortran, Pascal, and C 



For example, on a Lisp host: 

L7SPM-ii r O/STlCDROMn:>DISTRIBUTION>8_3_SOURCE_DIST_1 . TAPE 
and on a Sun host: 

sun-host : /cdrom/di stri buti on/8_3_source_di st_ 1 . tape 
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3. For each distrubution image, click on [Initialize Restoration], and use the 
mouse to deselect systems that you do not want to restore from the menu. 
For more information on using the Restore Distribution frame, see the section 
"Restore Distribution Frame". 

Once you have deselected those systems that you don't want to restore, click 
on [Perform Restoration]. This restores the selected systems from the distri- 
bution image. Note that restoring the FPC distribution image is optional. 

All sites must restore the following systems: 

LEGAL-NOTICE 

MACRO-CALLS-DATABASE 

TV-FONTS 

All sites that include an Ivory-based machine (NXP, Maclvory, XL, or Symbol- 
ics UX) must restore the following systems: 

IFEP-DISTRIBUTION (Ivory FEP Kernel and IFEP Overlays) 

All Standalone XL and Maclvory sites must restore the following systems: 
STANDALONE-SITE-FILES 

All sites that include a 3600 Family machine must restore the following sys- 
tems: 

NFEP-OVERLAYS 
MICROCODES 

All sites who want up-to-date online Genera sources should restore the follow- 
ing systems: (Note that most of the non-loaded systems also include sources.) 

SYSTEM 

CLOS 

DEVELOPMENT-UTILITIES 

OLD-TV 

UTILITIES 

SERVER-UTILITIES 

ZMAIL 

LMFS 

LMFS-DEFSTORAGE 

SCSI 

TAPE 

EXTENDED-HELP 

CL-DEVELOPER 

RPC 

EMBEDDING-SUPPORT 

MACIVORY-SUPPORT 
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UX-SUPPORT 

RPC-DEVELOPMENT 

MACIVORY-DEVELOPMENT 

UX-DEVELOPMENT 

ZWEI 

SERIAL 

HARDCOPY 

NSAGE 

IP-TCP 

X-REMOTE-SCREEN 

X-CLIENT-FONTS 

Sites with Maclvory machines who want up-to-date online Maclvory C sources 
should restore the following systems: 

MACIVORY-MACINTOSH-SOFTWARE (C sources for the Macintosh 
side of Symbolics Maclvory software) 

All sites who want up-to-date online Genera documentation should restore the 
following systems: 

DOC (Genera Documentation Database) 
IP-TCP-DOC 

NFS-DOCUMENTATION 
X-DOCUMENTATION 

All sites might need to restore the following non-loaded systems: 

PRINT (Print Spooler) 

LGP2-SUPPORT (LGP2/3 Printer support) 

DMP1-SUPPORT 

MAILER 

DOMAIN-NAME-SERVER 

All sites may choose to restore the following non-loaded systems: 

CLIM (Common Lisp Interface Manager) 

GENERA-CLIM 

CLX-CLIM 

POSTSCRIPT-CLIM 

CLIM-DEMO 

CLIM-COMPATIBILTY 

CLIM-DOC 

CLIM-TEST-SUITE 

CLIM-TUTORIALS 

METERING 

CONVERSION-TOOLS (Zetalisp to Common Lisp; Flavors to CLOS) 

HACKS (demos) 
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EXAMPLES 

NFS-SERVER (includes NFS-CLIENT) 

X-SERVER 

X-SERVER-FONTS 

STATICE-RUNTIME (CLOS-based Statice-Runtime) 

FLAVORS-STATICE-RUNTIME (Flavors-based Statice-Runtime) 

DBFS-UTILITIES (Statice backup utilities) 

MAC-DEX (a sample Maclvory application) 

HYPERCARD-MACIVORY (Maclvory interface to HyperCard) 

HELPFUL-TOOLS (utilities for upgrading namespace and dialnet to Genera 8.0) 

8-1-NETBOOT-COMPATIBILITY-PATCH (allows 8.1 netboot servers to serve 

8.3 clients) 

UNSUPPORTED (systems that are no longer maintained) 

Sites interested in experimenting with RPC can choose to restore the follow- 
ing systems: 

MACINTOSH-EXAMPLES (Maclvory example files) 
ADDITIONAL-RPC-EXAMPLES (RPC example files) 
UX-RPC-AND-FRIENDS (UX RPC code) 

Sites with 3600 Family machines can choose to restore the .bin files for the 
following systems, which can be loaded into 3600 Family Genera worlds: 

DEPENDENT-MODULES 
X-REMOTE-SCREEN 
X-DOCUMENTATION 
MACIVORY-SUPPORT 
UX-SUPPORT 
RPC-DEVELOPMENT 
MACIVORY-DEVELOPMENT 
UX-DEVELOPMENT 

Sites with Maclvory Delivery machines can choose to restore the .ibin files 
for the following systems, which can be loaded into Maclvory Delivery worlds: 
(Note that for the Dex-Doc system, .sab files as well as ibin files must be 
restored.) 

DEPENDENT-MODULES 

IP-TCP 

IP-TCP-DOC 

NFS-CLIENT 

NFS-DOCUMENTATION 

X-REMOTE-SCREEN 

X-DOCUMENTATION 

ZWEI 

SERIAL 
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HARDCOPY 

NSAGE 

DELIVERY-DOCEX (Delivery Document Examiner) 

DEX-DOC (documentation for Delivery Docex) 

UX-SUPPORT 

RPC-DEVELOPMENT 

MACIVORY-DEVELOPMENT 

UX-DEVELOPMENT 

Sites with UX Delivery machines can choose to restore the .ibin files for the 
following systems, which can be loaded into UX Delivery worlds: 

ZWEI 

SERIAL 

HARDCOPY 

MACIVORY-SUPPORT 

RPC-DEVELOPMENT 

MACIVORY-DEVELOPMENT 

UX-DEVELOPMENT 

Sites with 3600 Family machines can choose to restore the following system: 
MICROCODE-SYMBOL-TABLES (for debugging purposes) 



Copying New Flod Files 

New flod files are available for Ivory machines upgrading from previous releases of 
Genera to Genera 8.3. 

This step should be skipped when installing a new UX machine, because the in- 
stallation program performs it automatically. 

Copy the newest FEP software to the FEP file system on each of your Symbolics 
machines. For Ivory-based machines this includes FEP kernel and flod files. 

Give the following command at a Lisp Listener: 

Copy Flod Files :version 1328 

Answer "Yes" to the query about updating the hello.boot file. By doing this, your 
hello.boot file will automatically be updated to scan the new flod files. 

For information about the Copy Flod Files command, see the section "Copy Flod 
Files Command". 

To use the new flods, you must cold boot the machine's FEP. Follow the instruc- 
tions for your machine type: 

After you have restored the documentation, sources, examples, fonts, and non- 
loaded systems, you are ready to make customized Genera 8.3 user and server 
worlds. (For further information on this topic, see the section "Customizing and 
Saving Worlds".) 
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Making Customized Genera User and Server Worlds 

Follow these instructions to make customized worlds containing the software you 
will be using at your site. For information about netbooting, See the section "Net- 
booting". For more information about Loadable Systems, see the section "Loadable 
Systems for All Machine Types". 



Making Worlds for User Machines 

We recommend the use of Incremental Disk Save (IDS) for customized worlds. 
(This makes it easier to distribute newer worlds to machines with small disk con- 
figurations.) 

1. Boot the site-configured world with IDS enabled. (On Ivory-based machines, 
check to see that your hello.boot file contains a Set Boot Options command 
line with the keyword and value :IDS Enable. On 3600-series machines, check 
that your boot. boot file contains an Enable IDS command line). If you have 
multiple machines at your site, do not use your namespace server machine to 
boot this world. 

2. Disable Services, using the Disable Services command, as shown: 

Disable Services 

3. Log in as the default system user. Type to the command prompt: 

Login Lisp-Machine 

This command line logs you in as the default user and is useful during instal- 
lation procedures, when you must perform certain operations after cold boot- 
ing. 

4. Load any software you want to include in the world such as non-loaded sys- 
tems or layered products. For example, to load the non-loaded system called 
Metering, type: 

Load System Metering 

For more information on loadable systems, see the section "Loadable Systems 
for All Machine Types". 

5. Optionally, use the Optimize World command: 

Optimize World 

The Optimize World command reorganizes the world to improve paging per- 
formance. It increases the size of an IDS world, however. More information is 
available about the Optimize World command. See the section "Optimize 
World Command". 

6. Save the new world, using either the Save World Incremental command or 
the Save World Complete command. This world will serve as the base world 
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for all of the non-server machines at your site. For example, to save an incre- 
mental Metering world using Genera 8.1 software, and based on the site- 
configured world: 

Save World Incremental FEP0:>Inc-Metering-8-1-f rom-Inc-Site. ilod 

Information is available about which of the two Save World commands to use. 
See the section "Save World Command". 

Once you have created these worlds, you can move them out to the appropri- 
ate machines, using the Copy World command. 

Note: The . i 1 od file extension indicates world-load files for Ivory-based ma- 
chines, just as the . 1 oad file extension indicates world-load files for Symbolics 
3600-family machines. Files with the . i 1 od extension can be copied only be- 
tween Ivory-based machines. Files with the . 1 oad extension can be copied only 
between Symbolics 3600-series machines. 



Loadable Systems for All Machine Types 



CLIM 

CLIM stands for Common Lisp Interface Manager. It is a portable, powerful, high- 
level user interface management system toolkit intended for Common Lisp software 
developers. 

For more information about CLIM, see the section "Common Lisp Interface Manag- 
er (CLIM): Release 1.0" and see the document Genera 8.3 Release Notes. 

If you want online access to the CLIM tutorials, make sure that you have restored 
the CLIM-TUTORIAL files from the Genera source tape image. 

No documentation available for section Installing CLIM 2.0. 

The CLIM Lisp Listener is bound to SELECT -A, (SELECT -synbol-sh if t-L). 



CLIM-Demo 

The CLIM Demos provide examples of small and medium-sized applications using 
CLIM. 

For more information about the CLIM Demos, see the section "Using the CLOE 
CLIM Demos". 

Before loading the CLIM Demo system, CLIM must be loaded. 

To load the CLIM Demos, type 
Load System CLIM-Demo 

To run the CLIM Demos in Genera, type 
(clim-demo: :start-demo) 
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CLIM-Doc 

CLIM Doc contains the online documentation for Symbolics CLIM. 

CLIM Doc depends on packages defined in the CLIM system. 

To load CLIM Doc, type 

Load System CLIM-Doc 

Print 

The Print system defines the Genera Print Spooler. The Print Spooler manages 
multiple print requests sent to a printer, from any number of users. You must load 
the Print system on Symbolics hosts designated as print spoolers. 

For more information about Printers and Print Spoolers, see the sections "In- 
stalling a Printer" and "Defining the Print Spooler" in Site Operations. 

If you are using Symbolics LGP2 or LGP3 printers, make sure that you have re- 
stored the LGP2-SUPPORT files from the Genera source tapes. If you are using 
Symbolics DMP1 printers, make sure that you have restored the DMP1-SUPPORT 
files from the Genera source tapes. Note that the LGP2-SUPPORT and DMP1- 
SUPPORT systems are not loadable systems, they just contain fonts and metric 
files which the Print software expects to find on your disk. 

To load the Print system, type 
Load System Print 

The Print Spooler activity is bound to SELECT-S. 



Mailer 

The Mailer system defines the Genera Store-and-Forward Mailer. The Mailer is a 
program that provides mail forwarding and delivery services to users at a site. The 
Mailer is distinct from Zmail, which is a user program for reading and composing 
mail. You must load the Mailer system on Symbolics hosts designated as mail 
servers. 

For more information about the Mailer, see the sections "Symbolics Store-and- 
Forward Mailer" and "Installing and Configuring the Mailer" in Document Examin- 
er (see the section "Reading Online Documentation"). 

The mailer does not depend on any other loadable systems. However, if you wish 
to send and receive mail from other sites on the ARPA Internet, you may need to 
set up a Name server at your site. See the section "Loadable Systems on the CD- 
ROM - Domain Name Server". 

To load the Mailer system, type 
Load System Mailer 

The Mailer Activity is bound to SELECT -0. 
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Domain Name Server 

The Domain Name Server software enables a Symbolics computer to act as a 
Name server host. A Name server provides other hosts on the network with infor- 
mation about the hosts in your domain. Hosts inside and (optionally) outside your 
site consult your Name server about objects in your domain. You must load the 
Domain Name Server system on Symbolics hosts designated as Name servers. Note 
that it is not necessary to load the Domain Name Server system on hosts which 
serve only as central name resolvers for your site. 

For more information about Domain Names, Name servers and central name re- 
solvers, see the section "Internet Domain Names" and see the section "Installing 
the Internet Domain Names System". 

The Domain Name Server system does not depend on any other loadable systems. 
However, a Symbolics host that is designated as a Name server for the ARPA In- 
ternet must run IP/TCP, because it must be capable of communicating with other 
hosts on the Internet using IP/TCP. See the "IP-TCP" description below. 

To load the Domain Name Server system, type 
Load System Domain-Name-Server 

The Domain Name Server activity is on Select-i. 



Metering 

The Metering system defines a uniform interface to the various Genera metering 
tools. This interface makes it convenient to meter different aspects of program 
performance, such as time, paging, and consing. 

For more information about Metering, see the section "Metering a Program's Per- 
formance". 

The Metering system does not depend on any other loadable systems. 

To load the Metering system, type 

Load System Metering 

The Metering Interface activity is bound to SELECT-^. 

Conversion-Tools 

The Conversion Tools system defines special-purpose Zmacs commands which par- 
tially automate the code conversion process. Tools are included for the following 
types of conversions: CLIM 1.0 to CLIM 2.0, DW to CLIM, Flavors to CLOS, Zetal- 
isp to Common Lisp, Symbolics Common Lisp to portable Common Lisp, and Pack- 
age Conversion. 

For more information about Conversion Tools, see the section "Conversion Tools". 
For more information about converting from Dynamic Windows to CLIM, see the 
section "Converting an Application From DW to CLIM". 

The Conversion Tools system does not depend on any other loadable systems. 
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To load the Conversion Tools system, type 
Load System Conversion-Tools 

Hacks 

The Hacks system contains Genera Demos. 

For more information about the Genera Demonstration facility, see the section 
"The Demonstrations Facility". 

The Hacks system does not depend on any other loadable systems. 

To load the Hacks system, type 
Load System Hacks 



IP-TCP 

The IP/TCP software package enables a Symbolics computer to communicate with 
other systems supporting the ARPA Internet protocol family. Load IP/TCP on ma- 
chines which will use IP/TCP protocols for remote login, file transfer, and/or elec- 
tronic mail and messages. 

For more information about IP-TCP, see the document Symbolics IP/TCP Software 
Package. 

The IP-TCP system does not depend on any other loadable systems. Note that all 
Genera 8.3 worlds, except the Genera 8.3 Maclvory delivery world, contain IP-TCP. 

To load the IP-TCP system, type 
Load System IP-TCP 



IP-TCP-Doc 

IP-TCP Doc contains the online documentation for Symbolics IP-TCP. 

IP-TCP Doc depends on packages defined in the IP-TCP system. Note that all Gen- 
era 8.3 worlds, except Genera 8.3 Maclvory Delivery worlds, contain IP-TCP Doc. 

To load IP-TCP Doc, type 

Load System IP-TCP-Doc 

NFS-Server and NFS-Client 

Symbolics NFS is a fully symmetrical implementation of the Sun Net-work File 
System protocol, as specified in the Sun Network File System Protocol Specifica- 
tion, Revision B of 17 February 1986. Symbolics NFS allows your Symbolics ma- 
chine to act as an NFS client or server or both. Load the NFS Server system on 
Symbolics machines which will act as NFS servers (NFS-Client is a component sys- 
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tem of NFS-Server, and will be loaded automatically when you load NFS-Server). 
Load the NFS Client system on Symbolics machines which will act as NFS clients. 

For more information about Symbolics NFS, see the document Symbolics Network 
File System (NFS) User's Guide. 

The NFS Server and NFS Client systems depend on RPC and IP-TCP. 

Note that all Genera 8.3 worlds, except the Genera 8.3 Maclvory Delivery world, 
contain RPC, IP-TCP and NFS Client. 

To load the NFS-Server system, type 
Load System NFS-Server 



NFS-Documentation 

NFS Documentation contains the online documentation for Symbolics NFS. 

NFS Documentation depends on packages defined in the NFS system. Note that all 
Genera 8.3 worlds, except the Genera 8.3 Maclvory Delivery world, contain NFS 
Documentation. 

To load NFS Documentation, type 

Load System NFS-Documentation 

X-Server 

The Symbolics X Server program handles X protocol output and input requests 
from other systems on the network and performs the requested operations on the 
local system's screen. It allows you to operate X client applications (such as 
"xterm") running on other systems from your Symbolics Computer's console. The 
Symbolics X Server only works on non-embedded machines. On embedded machines 
(Maclvory or UX), run an X Server on the embed host, such as MacX for Macin- 
tosh or OpenWindows for Sun. 

For More information about the Symbolics X Server, see the document Symbolics X 
Window System User's Guide. 

The X-Server system does not depend on any other loadable systems. The C Run- 
time system, which includes software to support the C language implementations 
of the X Server, is a component system of X-Server. As long as you have restored 
C-Runtime from the Genera Source tape image, C-Runtime will automatically be 
loaded when you load the X-Server system. The standard set of X fonts are includ- 
ed in the X Server distribution, in the Server Native Format used by the X Server. 
To use these, make sure that you have restored the X-SERVER-FONTS files from 
the Genera Source tape image. 

To load the X-Server system, type 
Load System X-Server 

The Xll Server activity is bound to SELECT-SDURRE. 
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X-Remote-Screen 

X Remote Screen is the client side of Symbolics X Windows. In X Windows, the 
client is the application seeking to present a user interface, and the server is a 
virtual console capable of doing so. The Genera X client supports multiple user in- 
terfaces simultaneously, possibly displayed on different consoles. 

For More information about Symbolics X Remote Screen, see the document Sym- 
bolics X Window System User's Guide. 

The X-Remote-Screen system depends on RPC, Embedding-Support, and IP-TCP. 

If you wish the Genera X Client to use Genera X fonts instead of the standard 
75dpi X fonts, make sure that you have restored the X-CLIENT-FONTS files from 
the Genera Source tapes, and that you have done any necessary server-dependent 
work to get the Genera X Client to use the Genera fonts. Note all Genera 8.3 
worlds, except the Genera 8.3 Maclvory Delivery world and the Genera 8.3 3600- 
family distribution world, contain X-Remote-Screen. 

To load the X-Remote-Screen system, type 
Load System X-Remote-Screen 



X-Documentation 

X-Documentation contains the online documentation for Symbolics X Windows 
(both the Symbolics X Server and X Remote Screen). 

X-Documentation does not depend on any other loadable systems. Note all Genera 
8.3 worlds, except the Genera 8.3 Maclvory Delivery world and the Genera 8.3 
3600-family distribution world, contain X-Documentation. 

To load X Documentation, type 

Load System X-Documentation 



Statice-Runtime 

Statice Runtime is a subset of Statice, an object-oriented database system for the 
Genera programming environment. Statice-Runtime enables Genera users to use, 
access, and maintain a Statice database. Statice Runtime does not include tools for 
developing Statice applications - those tools are available separately, in the Statice 
Developer layered product. 

As of release Genera 8.3, Statice Runtime is a CLOS-based implementation. For 
compatability purposes, Flavors-based Runtime is also included. For more informa- 
tion about CLOS Statice and Flavors Statice, see the section "Changes to Statice 
and CLOS". 

For more information about Statice Runtime, see the section "Statice Runtime". 

The Statice-Runtime system does not depend on any other loadable systems. 

To load the Statice Runtime CLOS-based system, type 
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Load System Statice-Runtime 

To load the Statice Runtime Flavors-based system, type 
Load System Flavors-Statice-Runtime 

DBFS-Utilities 

The DBFS-Utilities system defines utilities for making backup copies of databases 
stored in a Statice File System. If a disk containing a Statice File System is dam- 
aged or destroyed, a backup copy of the database can be restored onto a fresh disk. 

For more information about Statice backup utilities, see the section "Statice File 
System Operations Program". 

DBFS-Utilities depends on Statice-Runtime. Before loading DBFS-Utilities, make 
sure that the Statice-Runtime system is loaded on your machine. 

To load the DBFS-Utilities system, type 
Load System DBFS-Utilities 

The Statice File System Operations program is bound to SELECT -8 (SELECT -syn- 
bol-shift-D). 

Mac-Dex 

Mac-Dex is the Macintosh Document Examiner, a sample Maclvory application. 
Mac-Dex is provided as an example of how to write an application which presents 
a Macintosh style interface using Symbolics' standard Macintosh application and 
zl-user:define-remote-program-framework. The Mac-Dex system is the Lisp side 
of the Mac Dex application, which is our standard Macintosh application config- 
ured to run Mac-Dex. Loading Mac-Dex on a 3600-family machine (or other non- 
Maclvory Symbolics machines) would allow you to use Mac-Dex from a non-NuBus 
Macintosh by talking to your 3600. 

For more information about using Symbolics' standard Macintosh application, see 
the section "Setting the Size of Application Icons That Use Ivory". 

The Mac-Dex system depends on RPC, Embedding-Support, and Maclvory-Support. 
On 3600-family machines, load the RPC, Embedding-Support, and Maclvory-Support 
systems before loading Mac-Dex. Note that all Ivory distribution worlds already 
contain RPC, Embedding-Support, and Maclvory-Support. 

To load the Mac-Dex system, type 
Load System Mac-Dex 

To run Mac Dex, do the following: 

1. Load the system Mac-Dex into Genera. 

2. Use [File / Quit] to get out of Genera. 
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3. Double-click on the Mac Dex icon, located in the Maclvory Applications folder. 

You do not need to run the Genera icon when you run the Mac Dex applica- 
tion. The Mac Dex application will boot your Ivory if it is not booted. To 
access Genera documentation via Mac Dex, use the menu titled Lookup in the Ap- 
ple menu bar. 



Hyper C ar d-Madvory 

The HyperCard-MacIvory system contains the Maclvory interface to HyperCard. It 
also includes a collection of demos that illustrates the close communication and in- 
tegration possible between Ivory and a host HyperCard application. 

For more information about the HyperCard-MacIvory system, see the section 
"Maclvory Interface to HyperCard". 

The HyperCard-MacIvory system depends on Mac-Dex. Note that the HyperCard in- 
terface always uses an embedded channel, so loading HyperCard-MacIvory is only 
useful on a Maclvory. 

To load the HyperCard-MacIvory system, type 
Load System HyperCard-MacIvory 



Making Worlds for Server Machines 

Server Machines: 

If you have server machines that run additional software (such as Print, Domain 
Name Server, or Mailer), follow the procedure used in "Making Worlds for User 
Machines" and build an IDS world, with the appropriate server systems loaded, for 
use on these machines. 

Make non-namespace server worlds on non-namespace server machines. This will 
enable non-namespace servers to boot more quickly, because their worlds will be 
smaller. 

Namespace Server Machines: 

Since namespace server machines load all the current namespace information into 
virtual memory, worlds saved on them are larger and boot more slowly than those 
saved on non-namespace server machines. Follow the procedure used in "Making 
Worlds for User Machines" and build an IDS world, with the appropriate server 
systems loaded, on a namespace server machine. 



Backing Up Worlds to Tape 

Back up the world(s) you just created (and the appropriate microcode) to tape. For 
complete information, see the section "FEP-Tape System" in Site Operations. Here 
is the procedure in brief: 
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1. Type the command in the Lisp Listener: 

Select Activity FEP-Tape 

2. Use the command Add File to add a single file to the list of files to be writ- 
ten to tape. For example, type to the FEP-Tape command prompt: 

Add File the pathname of the base site world 

Add File other world loads and microcodes you want to back up 

Or, you can click on [Add File]. If you back up both the world load and the 
microcode files, these files can both be restored if needed. 

3. Use the command Write Tape to write the file to tape; type this to the FEP- 
Tape command prompt: 

Write Tape 

We recommend that you type the Write Tape command, rather than clicking 
on the [Write Tape] menu item, because typing the command gives you more 
control over the tape specification. 



Special Installation Situations 

During site configuration and your software installation, you may encounter special 
situations. Such situations include: 

• Adding non-Symbolics computers to your site. 

• Installing software from a CD-ROM drive that is on a non-Symbolics machine (a 
Sun workstation). 

• Storing documentation, sources, examples, fonts, and non-loaded systems on a 
non-Symbolics computer. 

This chapter contains information about these special situations. 



Adding Non-Symbolics Computers to Your Site 

Once the non-Symbolics hardware and software have been correctly installed (and 
verified) at your site, use the Namespace Editor (specifically, the Edit Namespace 
Object command) to add non-Symbolics machines to your namespace database. 
More information is available about the Namespace Editor. 

See the section "Using the Namespace Editor". 

• If another host at your site is already running the same operating system as the 
new host, use the [Copy Object] menu item in the Namespace Editor window. Be 
sure to change the network address(es) and name(s), though. 
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• If no other host at your site is already running the same operating system as 
the new host, use the [Create Object] menu item in the Namespace Editor win- 
dow. For information about the attributes of a new host, see the section "At- 
tributes for Objects of Class "Host"". 



Using a CD-ROM as a SYS Host 

In order to use a CD-ROM as a SYS host, the CD-ROM drive must be connected to 
one of: 

• an NXP1000 

• an XL Family machine running Genera 8.1.1 or later 

• a Maclvory running Genera 8.1.1 or later 

• a Sun-4 

Note: Genera 8.1 is not sufficient for a Symbolics machine to serve as a CD-ROM 
SYS host. 

The procedure for setting up your site to use a CD-ROM SYS host is as follows: 

1. Copy everything from the >sys>site> directory on the CD-ROM to the SYS:SiTE; 
directory for your site. The SYS:SiTE; directory for a site is specified in the 
Site namespace object. 

Copy File HOST |CDROMft:>SYS>SITE>x.x ; x SYS : SITE; *.*. * 

Note: If your CD-ROM drive is on a Sun, this step must be executed in a 
Genera 8.3 world as follows: 

Copy File sun-host :/cdrom/sys. set/site/* sys:site;*.x.x 

2. Edit your sys:SITE;SYS.translations file to translate logical pathnames to physi- 
cal pathnames of files on the CD-ROM. After making the necessary changes, 
save and load the new sys.translations file, or build it into your site- 
configured Genera 8.3 worlds. Once the updated translations are loaded, you 
should be able to access files on CD-ROM as easily as you would access files 
on a LMFS. 

In the following examples, HOST is the name of the NXP, XL, or Maclvory 
CD-ROM host, and n in CDROMn is the SCSI address of the CD-ROM drive. 

If all machines at your site are running Genera 8.3, and if your CD-ROM 
drive is connected to an NXP, XL, or Maclvory, use the following example 
translations as a guide: 

;;; -x- Mode: LISP; Syntax: Common-lisp; Package: USER -x- 
(fs: set-logical -pathname-host "SYS" translations 
' (("sys:xx;x.x.x" "HOST | CDROMft:>SYS>xx>x. X; x") ) ) 
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If your CD-ROM drive is connected to a Sun, use the following example trans- 
lations as a guide: 

;;; -*- Mode: LISP; Syntax: Common-lisp; Package: USER -*- 
(fs: set-logical -pathname-host "SYS" translations 
' ( ( " sys : xx ; x . x . x" " sun-host : /cdrom/sys . sct/xx/x" ) ) ) 

If some machines at your site are running a release older than Genera 8.3, 
use the following example translations as a guide: 

;;; -x- Mode: LISP; Syntax: Common-lisp; Package: USER -x- 
(mul tiple-value-bind (major-version minor-version) 
(set : get- r el ease-versi on) 
(select major-version 

;; Translations for Genera 8.1, 8.1.1 
(8 (selector minor-version equalp 
(("1.1") 
(fs: set-logical -pathname-host "SYS" translations 

' ( (" sys : xx; x . x . x" " ACME-SMBX : >rel -8-1 >sys>xx>x .*.*"))))) 
(("2 NXP") 
(fs: set-logical -pathname-host "SYS" [translations 

' (("sys:xx;x.x.x" "HOST | CDROMn:>sys>xx>x. x; x") ) ) ) 
((3) 
(fs: set-logical -pathname-host "SYS" [translations 

' (("sys:xx;x.x.x" "HOST | CDROMn:>sys>xx>x. x; x") ) ) ) 
(otherwise (error "~A ~A unknown release or system version. ~2T 

Edit SYS:SITE;SYS. TRANSLATIONS to add this system, 
major-version minor-version)))) 
(otherwise (error "~A ~A unknown release or system version. ~2T 

Edit SYS:SITE;SYS. TRANSLATIONS to add this system, 
major-version minor-version)))) 

If you wish to use the CD-ROM as the sys host for only specific parts of the 
Genera 8.3 documentation, sources, examples, fonts, and non-loaded systems, 
use the following example translations as a guide (This example assumes that 
all Symbolics machines at your site are running Genera 8.3): 

;;; -x- Mode: LISP; Syntax: Common-lisp; Package: USER -x- 
(fs: set-logical -pathname-host "SYS" [translations 
;; Access documenatation and fonts from the CD 
' (("sys:doc;xx;x.x.x" "HOST |CDROMft:>SYS>DOC>xx>x.x;x") 
("sys: fonts; xx; x.x.x" "HOST |CDROMft:>SYS>FONTS>xx>x.x;x") 
;; Access everything else from a LMFS on a file server 
(" sys : xx; x . x . x" " SMBX : >rel -8-3>sys>xx>x .*.*"))) 
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Known limitations and problems with using a CD-ROM SYS host 

1. The ISO9660 filesystem does not understand unusual characters such as +, $, 
and & in pathnames. There are a few pathnames in the Genera distribution 
which contain such characters. If you run into one, simply take the retry op- 
tion to specify another pathname, and respecify the same pathname, but drop 
the offending character. For example, 

SYS : EMBEDDING; MACIVORY; TOOLBOX; LI SP+C-SCT-SUPPORT . BIN appears as 
SYS : EMBEDDING; MACIVORY; TOOLBOX; LI SPC-SCT-SUPPORT.BIN 

in the CD-ROM filesystem. 

2. The ISO9660 filesystem limits the length of file and directory names to 31 
characters, including periods and file types. File names longer than this are 
truncated. There are many truncated pathnames in the Genera distribution, 
however only three files produced ambiguous pathnames when truncated. On 
the Genera CD-ROM, we renamed these three files to avoid truncation prob- 
lems: 

SYS: EXAMPLES; CONSTRAINT-FRAME-LANGUAGE-1 .LISP 
SYS : EXAMPLES ; CONSTRAI NT-FRAME-LANGUAGE-2 .LISP 
SYS : EXAMPLES ; CONSTRAI NT-FRAME-LANGUAGE-3 .LISP 

are named 

SYS: EXAMPLES; CONSTRAINT_FRAME_LANGUAGE_. LISP 
SYS : EXAMPLES ; CONSTRAI NT_FRAME_LANGUAG_2 .LISP 
SYS : EXAMPLES ; CONSTRAI NT_FRAME_LANGUAG_3 .LISP 

Note that the ISO9660 translations rules automatically do the correct thing 
for all other truncated pathnames on the CD-ROM. For example, Genera auto- 
matically translates 

SYS:METERING;INTERFACE;STATISTICAL-CALL-TREE-METERING-RUN.IBIN 
to the correct CD-ROM pathname: 

CDROMn : >sys>meteri ng>i nterf aces>stati sti cal_cal l_tree_mete . i bi n 

3. When using a CD-ROM as a SYS host, you must reset access paths whenever 
you change CD disks. 



Storing Genera Sources on a Non-Symbolics Machine 

You can use a UNIX machine running NFS as a file server to store your Symbol- 
ics sources. 

Use this example for your sys.translations file: 
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;;; -*- Mode: LISP; Syntax: Common-lisp; Package: USER -*- 
(fs: set-logical -pathname-host "SYS" translations 

' (("sys:**; " "ACME-UNIX: /us r/share/symbol ics/rel-8— 4/sys.sct/**/"))) 

If you are running multiple releases (for example, some combination of Genera 8.3 
and Genera 8.4), use the following example: 

;;; -*- Mode: LISP; Syntax: Common-lisp; Package: USER -*- 
(multiple-value-bind (major-version minor-version) 
(set : get- r el ease-versi on) 
(select major-version 

;; Translations for Genera 8.1.1, 8.2, and 8.3 
(8 (selector minor-version equalp 

(("3") (fs: set-logical -pathname-host "SYS" [translations 
' (("sys:**;" 

" ACME-UN I X : /usr/share/symbol i cs/rel -8-3/sys . set/**/" ) ) ) ) 
((4) 
(fs: set-logical -pathname-host "SYS" [translations 
' (("sys:**;" 

" ACME-UN I X : /usr/share/symbol i cs/rel -8-4/sys . set/**/" ) ) ) ) 
(otherwise (error "~A ~A unknown release or system version. ~2T 

Edit SYS:SITE;SYS. TRANSLATIONS to add this system, 
major-version minor-version))))) 
(otherwise (error "~A ~A unknown release or system version. ~2T 

Edit SYS:SITE;SYS. TRANSLATIONS to add this system, 
major-version minor-version))) 

Using SCT with a UNIX File System 

The System Construction Tool (SCT) presents a special case in using UNIX backup 
files. SCT requires a version number for the files it uses. For directories main- 
tained by SCT, files are maintained so that the newest versions of the files have 
an explicit version number. (See the section "System Construction Tool" for back- 
ground information on SCT). 

Use the name of a UNIX directory to specify that files contained in it are to be 
maintained by SCT and should all end with explicit version numbers. If the name 
of a UNIX directory ends with the .set file extension, Symbolics NFS creates all 
new files under that directory with explicit version numbers. 

Here's an example. Suppose a sys. translations file looked like this: 

;;; -*- Mode: LISP; Syntax: Common-lisp; Package: USER -*- 

(fs: set-logical -pathname-host "SYS" [translations 

'(("**;" "ACME-UNIX: /usr/share/symbol ics/rel-8-0/sys.sct/**/"))) 

In this case, all new files created with Symbolics NFS under 
/usr/share/symbol i cs/rel -8-0/sys. set/ are created with explicit version numbers 
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in the newest versions of files, meeting SCT requirements. This is true for all sub- 
directories of a directory whose name ends in . set. 

The double-asterisk (**) wildcard can be used only in UNIX pathnames that are 
accessed by means of NFS. Other UNIX file protocols, such as FTP, do not recog- 
nize this wildcard. For further information on the use of the double-asterisk wild- 
card, see the section "LMFS Pathnames". 

Genera considers UNIX pathnames with any directory components ending in the 
string ".set" to be for SCT-maintained files, and hence to contain version numbers. 
The syntax that Genera uses for backup file version numbers in UNIX pathnames 
is a number surrounded by tildes separated by a dot from the file type. 

This pathname is considered to have a version number: 

ENIAC:/u0/mwra/visi-brain.sct/foo. 1 isp.~23~ 

So merging with it as a default behaves like this: 



Default 



Input 



Merged 



ENIAC:/u0/dpw.sct/code/foo. 1 isp. 23" 
ENIAC:/u0/dpw.sct/code/foo. 1 isp.~23~ 



bar. * 
* .bin 



ENIAC:/u0/dpw.sct/code/bar . 1 isp 
EN I AC : /u0/dpw . sct/code/f oo .bin 



Note that backup file version numbers are are not defaulted as part of the merg- 
ing operation. 

You can set the number of backup versions that are retained by Genera with the 
"NFS-GENERATION-RETENTION-COUNT User Property'Tor host namespace ob- 
jects. 



Miscellaneous CD-ROM Information 



Recommended Care and Handling of a 3M CD-ROM 

The CD-ROM itself is a piece of plastic worth several dollars. The value of the 
CD-ROM is in the information which it stores. The CD-ROM is resistent to dam- 
age from scratches, fingerprints, and dust. It is not, however, indestructible. To as- 
sure the information's integrity, 3M recommends observing the following: 

1. Handle the disc by the edges to prevent fingerprints on either surface of the 
disc. When removing the disc from the jewel box, be sure to press down on 
the middle hub of the jewel box to release the disc. Do not pull up hard 
enough on the disc to bend it more than a half (.5) inch before it releases. 
Place the disc carefully into the CD-ROM drive, making sure not to scratch 
the disc against the drive or any other obstruction. 

2. When the disc is not in use, place it in its jewel box. This prevents scratch- 
ing of the disc's surfaces. The information is covered by protective layers, but 
it is possible to scratch through the label and damage the information. Plac- 
ing an unprotected disc flat on a desk or table is inviting trouble. 
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3. Dust is attracted to the surface of a CD-ROM. This dust can affect the read- 
ability of the disc. Remove dust from the unlabeled side of the CD-ROM be- 
fore loading it into the drive. Dust carried into a drive can also be deposited 
on the lens assembly, which can affect readability of subsequent discs on the 
system. 

4. If the disc becomes soiled with fingerprints or spots, wipe it with a soft dry 
cloth. If the cloth alone does not remove the spot, attempt to fog the disc 
with your breath and rewipe. For severe spots resisting removal by this 
method, a small amount of ethyl alcohol can be placed on the cloth to dampen 
it. Using the dampened cloth, wipe the area. This method should only be used 
if the disc is unusable in its present state. 

5. No abrasive or solvent cleaners should be used on the disc. Do not use con- 
ventional vinyl record cleaning solutions because they contain chemicals that 
can damage a CD-ROM. 



Ejecting the CD From the Drive 

• On an NXP or an XL, press the eject button on the front of the CD-ROM drive. 



• 



On a Maclvory, use the Eject menu item in the File menu of the Macintosh 
Finder. 



• On a Sun, use the umount command to unmount the CD-ROM drive, then press 
the eject button on the front of the CD-ROM drive. For more information on the 
UNIX umount command, see the SunOS Reference Manual entry on umount. 



Reading Online Documentation 



Introduction to Document Examiner 

Document Examiner is a utility for finding and reading documentation. The entire 
Symbolics document set can be read using Document Examiner. 

You can look up documentation in Document Examiner's own window, in a Lisp 
Listener, or from the editor. No matter where you request to view documentation, 
Document Examiner manages all online lookup queries. 

Using Document Examiner is similar to using the printed documentation. For ex- 
ample, just as books in the document set are available on a shelf or on your desk, 
Document Examiner, when first selected, displays the names of all the books in 
the document set. See Figure 48. 

You can open to a book's table of contents and find a topic to peruse. You can also 
open a book to the topic and read through to the end of that topic. Similarly, Doc- 
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ument Examiner lets you scan a document's table of contents online and select the 
desired topic, or, if you know what you are looking for, you can "open" the docu- 
mentation set directly to any topic and read to the end of that topic. 

Just as you can browse through the index of a book to find the primary topic (and 
secondary topics) you want to read about, you can ask Document Examiner to show 
you all the topics that are indexed under a particular entry. 

The big difference between the Document Examiner and a book or set of books is 
that Document Examiner provides powerful tools for moving from one kind of in- 
formation to another. 

Document Examiner allows quick, direct access to all levels of information: 

• General, conceptual discussions of a topic 

• Reference material on a topic 

• Specific programming language information (for example, a Lisp function) 

How Documentation Is Stored 

The online documentation is kept in a documentation database, which consists of 
documentation binary files. When you boot your machine, the world load contains 
location information about the documentation topics, not the actual files them- 
selves; thus, world size is increased by only a few hundred pages by having the 
document set available. The documentation database is stored on a file server; 
when you request to see a documentation topic, the appropriate part of the appro- 
priate file is read in from the server. 

Each documentation topic is stored as a record in the documentation database. 
Each record contains information on a particular topic and is uniquely identified 
by a record name. For example, the section you are currently reading is a record 
whose name is "How Documentation is Stored". 

Records fall into two categories: 

• Object records documenting Lisp code objects, such as zhsetf or tvrmenu. 

• Concept records documenting abstract ideas that are not tied directly to code, 
such as "Introduction to Document Examiner" or "Show Documentation Com- 
mand". 

Records have types. Examples of object record types are Lisp function, flavor, and 
variable. Concept records are called sections. The documentation lookup commands 
use the type indicator to distinguish between like-named records. For example, if 
you request to see the documentation for error, Document Examiner lets you know 
that documentation exists for error as both a flavor and as a function. 

Records have topics. The Show Documentation command looks up records by their 
topics. The topic uniquely identifies a record. 
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Records also have keywords with them. A keyword is comparable to a word in an 
index entry. This record contains the keywords "documentation record". The Show 
Candidates command compares your lookup request to all the keywords and docu- 
mentation topic titles in the database. So, for example, if you want to find out 
what information is available on the general topic "record", Document Examiner 
includes the record you are now reading in its list of possible choices because 
"record" is one of its keywords. You can see the keywords for any record in the 
overview of the record. 



Help in Document Examiner 

Press the HELP key in the Document Examiner window to display a summary of 
commands. Clicking Left on [Help] in the command pane produces the same abbre- 
viated display. 

Complete documentation of all features is available by command is equivalent to 
clicking Middle on [Help] in the command pane or by typing Document Examiner 
Documentation at the prompt. 



Document Examiner Window 

You can select Document Examiner in one of two ways: 

• Keyboard: Press SELECT D or type Select Activity Document Examiner at the 
Command Processor. 

• Menu: Click on [Document Examiner] in the System menu. 

The Document Examiner window contains the following panes, as displayed in Fig- 
ure 64: 

• Viewer — where the documentation is displayed 

• Current candidates — list of current choices, usually resulting from a Show Can- 
didates or Show Table of Contents command 

• Bookmarks — list of topics you've looked at or indicated that you wanted to look 
at 

• Command — where you enter commands, either by mouse or by typing a com- 
mand 

Each of these panes is discussed in detail in this section. 



Viewer Pane 

The large area on the left of the window is called the Viewer pane. All the docu- 
mentation you select to read is displayed in the viewer. 
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Document Examiner 



Viewer: Default Viewer 



Current Candidates 

Genera Concepts 
Genera Workbook 
Genera User's Guide 
Genera Handbook 

Editing and Hail 

Progran Development Tutorial 

Synbolics Cannon Lisp — Language Concepts 

Synbolics Connon Lisp — Progranning Constructs 

Prcgranning the User Interface 

User Interface Dictionary 

Progran Deuelcpnent Utilities 

Hetworks 

Internals 

Site Operations 

Genera 8.0 Release Notes 

Genera 8.0 Software Installation Guide 

Converting to Genera Ivory 

Haclvcry User's Manual 

Haclvcry Progranner's Reference 

XL400 User's Manual 

Synbolics Haclvory Delivery User's Manual 

User's Guide to the Synbolics UX400 



Bookmarks 



Commands 



Show Candidates 

Show Documentation 

Show Overview 

Show Table of Contents 



Help 

Select Uiewer 

Reselect Candidates 

Read Private Document 



[Thu 11 Jan A:- 



Figure 64. Upon selection, the Document Examiner displays all the books in the 
document set. 



When you select a topic for viewing in Document Examiner, the topic is displayed 
at the end of the viewer and the topic's name is added to the list of bookmarks. 
Topics displayed in a viewer are separated by a light horizontal line. 

Certain items displayed in the viewer are mouse sensitive; for example, clicking 
Left on cross-references or the names of documented Lisp objects displays their 
documentation in the viewer, clicking Middle displays an overview of the topic (a 
summary of where it is and what it is), and clicking Right presents a menu of op- 
erations. Check the mouse documentation line for details. 

The viewer is a dynamic window, which gives you the ability to copy a region of 
text from the viewer into another window, such as Zmacs or Zmail. You can mark 
a region with the mouse by pressing the CONTROL key and push the marked text on 
the kill ring using s-W. For example, you can extract an interesting Lisp code ex- 
ample from a documentation topic and run it in an editor buffer or Lisp listener. 
Or you can include selections from the documentation in mail or text files. You 
can also search for a particular string using s-R to to search backward and s-S to 
search forward. For an introduction to using dynamic windows, see the section 
"Using Your Output History". 
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When you first select Document Examiner, you see the default viewer. It is labeled 
as such in the lower left-hand corner of the pane. You can create or select another 
viewer, just as you can create or select another editor buffer. To create a new 
viewer click Left on [Select Viewer] or enter the Select Viewer command and 
name a nonexistent viewer. You can see a mouse-sensitive list of existing viewers 
by pressing c-?. To go between two viewers, press c-m-L. To select another view- 
er, use Select Viewer. 

When you look up documentation in a Lisp Listener (using the Show Documenta- 
tion command) or in the editor (using n-Sh-D or n-H Show Documentation), book- 
marks for those topics are inserted in a special viewer called the Background view- 
er. 

Examples of Lisp code whose lines are wider than the viewer display with those 
lines wrapped around. When you need to see such examples in a more readable 
layout, use the Show Documentation command in a wider window, such as a Lisp 
Listener. 



Current Candidates Pane 

The upper right-hand pane of Document Examiner's window displays the names of 
those topics that are the current candidates, that is, a menu of choices from which 
you can select a topic for viewing. These candidate lists are produced by the Show 
Candidates and Show Table of Contents commands. 

When you first enter Document Examiner, the current candidates pane displays 
the list of documents registered in the documentation database, as displayed in 
Figure 64. Each time you use Show Candidates or Show Table of Contents, a new 
list of current candidates is generated and displayed. Note that lines that are 
wider than the current candidates pane are truncated. 

You can redisplay a list of candidates not currently showing by clicking on [Rese- 
lect Candidates] or using the Reselect Candidates command. You'll see a menu of 
all the documentation searches conducted during the current session. This list is 
helpful when, for instance, you need to cycle through several sets of candidates. 
Instead of having to remember exactly what you asked for each time you want to 

look at it, use the Reselect Candidates command and click on the candidates pane 
that you want to see. 



Bookmarks Pane 

The lower right-hand pane of the Document Examiner window contains a list of 
bookmarks. Bookmarks are the names of topics that you have displayed in the 
viewer or the names of topics that you want to display later on. Thus, a Document 
Examiner bookmark is similar to a bookmark you might place in a printed book — 
as a reminder of something you have just read and might want to reread or as a 
pointer to something you should read in the future. 

Document Examiner automatically inserts a bookmark for a topic when that topic 
is first displayed in the viewer. The list represents a history of your selections for 
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a particular viewer. You can also explicitly add a bookmark to the list of book- 
marks without having the topic displayed in the viewer. See the section "Putting 
Topics Aside for Future Reading". 

The list of bookmarks distinguishes between bookmarks whose topics have been 
displayed and those that have not. Topics that are displayed in the viewer are list- 
ed on a white background in the order in which you looked them up. Topics not 
displayed in the viewer follow and are listed on a gray background in the order in 
which you created the bookmarks. See Figure 49. 



Bookmarks 

FUHDEFIHE Function 

Set Network Address FEP Connand Section 
Set Ethernet Address FEP Connand Section 
* Custonizing and Saving Worlds Section 



Figure 65. The bookmarks pane shows which topics have been displayed in the 
viewer. 

Names that are wider than the bookmarks pane are truncated. 

You also use a set of bookmarks in creating a private document. See the section 
"Creating a Private Document". 



Command Pane 

The bottom portion of the Document Examiner window is called the command 
pane. It accepts hand-typed commands at the triangular Command Processor 
prompt to the left and displays a menu of Document Examiner command menu 
items to the right. 

The Command Processor offers completion on command names as well as topic 
names. The HELP key (after you type at least one character) displays a mouse- 
sensitive list of possible completions. Pressing HELP before you start to type a com- 
mand name displays the available commands. After you type at least one character, 
c-? displays a mouse-sensitive list of commands starting with the character or 
characters you have typed and c-/ displays a mouse-sensitive list of commands in- 
cluding the character or characters you have typed. 



Page 721 



The mouse documentation line, situated below the command pane, tells you how to 
use the mouse to activate a particular command from the menu. 

The following list describes the commands. All these commands are also available 
as menu items. 

• Help — offers a brief command summary. Or click Right on [Help]. 



• 



• 



• 



• 



• 



Document Examiner Documentation — displays the full Document Examiner 
documentation. Or click Middle on [Help]. 

Show Candidates — searches the entire database for documentation topics with 
titles or keywords that resemble or match what you're looking for and displays a 
list for you to choose from. 

Show Documentation — displays the documentation for a specific topic and is 
useful when you know exactly what you're looking for. 

Show Overview — displays basic information about a topic, including a tree 
graph that shows how the topic fits in with other topics and what keywords are 
specified for it. 

Show Table of Contents — displays the table of contents of a topic, that is, 
what other topics that topic includes. It is most useful for getting information 
about an entire chapter, section, or book. 

Reselect Candidates — displays a menu of all the candidates lists created for a 
particular viewer during the current work session. Candidates lists are created 
whenever you invoke the Show Candidates or Show Table of Contents com- 
mands. The display is a mouse-sensitive menu from which you can redisplay the 
results of a previously executed command. 

Select Viewer — changes from one viewer to another or creates a new one. You 
can create a new viewer by naming a nonexistent viewer in the Select Viewer 
command. You can move between two viewers by pressing c-m-L. 

• Remove Viewer — removes a viewer from the list of viewers. Also available 
from the menu presented when you click Right on [Select Viewer]. 

• Hardcopy Viewer — hardcopies the contents of a viewer. Also available from the 
menu presented when you click Right on [Select Viewer]. 

• Save Private Document — saves the list of bookmarks in the current viewer as 
a private document. This means you can create your own private document by 
creating bookmarks for one or more documentation records and then issuing this 
command to write the collection of bookmarks to a file. Also available from the 
menu presented when you click Right on [Read Private Document]. You can 
read or load a private document when you need it. It is not part of the docu- 



• 
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mentation database. See the section "Creating a Private Document". Read Pri- 
vate Document — allows you to view private document collections created from 
the documentation database. This command loads all the text associated with 
the private document into a viewer. 

Load Private Document — loads the bookmarks associated with a private docu- 
ment, but does not load the text. Also available from the menu presented when 
you click Right on [Read Private Document]. 

Hardcopy Private Document — sends all the text in a private document to a 
printer. Also available from the menu presented when you click Right on [Read 
Private Document]. 



Looking Up Documentation 

When you look through a printed book for information, you probably scan the table 
of contents to see how the book is organized and maybe skim a few chapters to see 
their major sections, perhaps inserting a bookmark or two when things look inter- 
esting. You might then look over the index to see the number and kinds of main 
and related entries on a particular subject. Sometimes you know exactly what you 
are looking for and can go directly to the section you want to read. 

Document Examiner provides a variety of commands and tools for online lookup 
that are analogous to the methods you use to examine a printed book, but are 
much more flexible. They are not limited to a single book, however, and they allow 
you to browse in the entire documentation database with just a few keystrokes and 
to take advantage of some "smart" aids to readers, such as the Show Candidates 
command. 

Requests for online lookup are always made with respect to a documentation topic 
name, which can be anything from the name of a document, chapter, or other book 
subdivision, to the name of a Lisp code object, like a function or flavor. Every Lisp 
object is documented in its own documentation record; the documentation topic 
name of the record is the name of the Lisp object. (You may need a package pre- 
fix. See the documentation for languages other than Lisp in case there are special 
procedures.) 

Show Documentation 

Displays the documentation for a specific topic name in the 
viewer and inserts a bookmark for the topic. You can do the 
same thing by clicking Left on the name of any documentation 
topic. You could look up the section you are reading now by us- 
ing Show Documentation and specifying "Looking Up Docu- 
mentation". 

Show Candidates Displays, after searching the database, all topic names that sat- 
isfy your lookup request. This is often the best way to search 
the documentation database. By default, Show Candidates uses 
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a heuristic, or "smart", searching strategy that allows you to 
see all the candidates that are close to what you asked for. For 
instance, if you specify "local" to Show Candidates, the candi- 
dates list includes "locals" "locative", "location", and "localize", 
as well as "local". Show Candidates lets you specify several 
search strategies. For information on these alternative search 
strategies, see the section "Show Candidates Command". 

Show Overview Displays the local context of a topic name, showing which topic 
includes it in the document hierarchy, which topics are on the 
same level, and which topics are included by it in the hierar- 
chy. This is good for examining the organization of topics and 
tracing topics to more general and more specific levels of ab- 
straction. The display also provides related information, such 
as, which documents a topic appears in and what keywords are 
associated with it. 

Show Table of Contents 

Displays the table of contents for a given topic name, showing 
the supplied topic name and all of its subordinate topics. This 
command is good for examining the organization of topics with- 
in a document. 

Genera's online documentation facility is flexible. You can look up information 
from several contexts — in a Lisp Listener, in an editor buffer, or directly in Doc- 
ument Examiner. Where you look up documentation probably depends on the kind 
of work you are doing and your own particular workstyle. 

• If you are programming in an editor buffer, you can use m-K Show Documenta- 
tion or its keyboard accelerator, n-sh-D. 

• In a Lisp Listener, you can issue Show Documentation at the Command Proces- 
sor, n-sh-R to see documentation for a Lisp function, n-sh-F to see documenta- 
tion for a flavor, or n-sh-U to see documentation for a Lisp variable. 

• If you plan to poke around or to read a great deal of documentation, you can 
take advantage of the extra features offered by Document Examiner, such as 
bookmarks and the Show Candidates command. Shifting to Document Examiner 
in such cases is easy. Bookmarks for all the topics you've looked at outside Doc- 
ument Examiner are inserted in the Background viewer. 

In addition, Document Examiner allows you to: 

• Insert a bookmark in a documentation topic, see the section "Putting Topics 
Aside for Future Reading". 



• 



Display the documentation for topics that are explicitly cross-referenced, see the 
section "Looking Up a Specific Topic". 
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• Display the documentation for implicit cross-references, such as the following 
mouse-sensitive reference to zhstring-capitalize-words. 

Any topic name appearing in any pane of the Document Examiner window is 
mouse-sensitive. That is, when you move the mouse over a topic name, the mouse 
highlights the name in an outline box; clicking one of the mouse buttons on a 
highlighed topic name causes some action to occur. Clicking Left displays the doc- 
umentation and clicking Middle displays the overview. 

Clicking Right brings up a menu of operations that can be performed on that topic 
name: 

View the documentation 
Hardcopy documentation 
Display a table of contents 
Insert a bookmark 
Display an overview 
Discard a topic 

The lookup commands distinguish among like-named topics. For example, if you 
use Show Documentation for evalhook, Document Examiner asks you to select 
evalhook as a function or as a variable. See Figure 50. Similarly, the lookup com- 
mands distinguish between Zetalisp objects and those that are Common Lisp or 
Symbolics Common Lisp objects; Zetalisp objects are displayed with the zl: package 
prefix. 



Current Candidates 

EURL 

Eval hook 

Evalhook Rccepts Optional Rpply Hook Rrgunent 

EURLH00K Function 

EURLH00K Variable 

Functions in the Connon Lisp Package with Incon 

Introduction to Evaluation 

Overview of the Debugger 

Rebound Variable Bindings During Evaluation 



Figure 66. Document Examiner lets you choose among like-named topics. 
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Looking Up a Specific Topic 

Document Examiner provides several ways to look up documentation for a specific 
topic, once you know the right topic name: 

• Use the Show Documentation command. 

• Use the mouse to display the documentation for cross-references and the names 
of Lisp objects. All topic names are mouse-sensitive; clicking Left on a topic 
name displays the associated documentation. The names of Lisp objects men- 
tioned in the documentation appear in a boldface character style. 

Example: the topic *load-set-default-pathname*, displayed in the viewer, men- 
tions the variable *load-pathname-defaults*, as shown in Figure 51. Clicking 
Left on the variable name displays the documentation for the topic "*load- 
pathname-defaults*". See Figure 51. 

• Use the mouse to display the documentation associated with current candidates, 
bookmarks, or topic names displayed in an overview or a table of contents. 



*load-set-default-pathname* Variable 

Controls whether the load and zl:load functions change 

the file loaded. The default 



|*load-pathname-defaults*] to reflect 

value is t. \ 



Figure 67. The names of Lisp objects displayed in the viewer are mouse-sensitive. 

In addition, you can look at documentation topics in the editor and in a Lisp Lis- 
tener. 



Show Documentation Document Examiner Command 

Show Documentation is useful when you know exactly what you are looking for. 
Show Documentation looks up a topic, displays it in the viewer, and, if it is a new 
topic, inserts a bookmark for the topic in the bookmarks pane. To invoke the com- 
mand you can either click on [Show Documentation] in the command menu or type 
Show Documentation in the command pane. The command prompts for a topic 
name. 

Clicking Left on a topic is the equivalent of Show Documentation. 

If you aren't quite sure what you're looking for, see the section "Show Candidates 
Command". 

Topic names for methods are of the form (flavor:method : generic- function-name fla- 
vor-name). Thus, to use Show Documentation for a method, give the topic name of 
the method in this form, for example: 

Show Documentation (flavor: method : set-edges tv:menu) 
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Show Documentation is also an editor command and a Command Processor com- 
mand. In an editor, m-K Show Documentation (or its keyboard equivalent n-sh-D) 
prompts you for a topic name, with completion. 

When you are typing in a Lisp Listener or a Lisp mode buffer in Zmacs, the fol- 
lowing commands give you documentation for the current Lisp object (the one 
nearest the cursor): 

n-sh-R Looks up the documentation for the current function. 

n-sh-U Looks up the documentation for the current variable. 

n-sh-F Looks up the documentation for the current flavor. 

You can use c-/ and c-? to find topic names containing or starting with the the 
sequence of characters you have typed so far. For example, 

Show Documentation search c-/ 

displays a mouse-sensitive list of all documentation topics containing "search" in 
their names. And, 

Show Documentation search c-? 

displays a mouse-sensitive list of all documentation topics whose names start with 
"search". 

See the section "c-? and c-/". 



Searching Through Documentation 

In addition to looking up specific topics online, you can search through the entire 
documentation database. Document Examiner includes many tools to make this 
searching easy. 

The Show Candidates command, for instance, can search for a broad range of pos- 
sible documentation topics using heuristic, or "smart", techniques. This means that 
the command locates a word and variations on it instead of searching for a strict 
match. The command defines the different variations for the word by checking for 
common suffixes using a technique called stemming. Thus, if you specify "local" to 
Show Candidates, the result includes "locals", "locative", "location", and "localize", 
as well as "local". 

Show Candidates isn't limited to documentation titles in doing the search. It 
searches through an index that contains all the words in topic titles and a list of 
keywords (somewhat like an index entry) for each documentation topic. 

If, in the course of your searching, you see topics that look interesting, you can ei- 
ther read them as you go or add bookmarks so you can look at them later. 

Document Examiner also helps you search by enabling you to jump from topic to 
topic. 
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• You can click on implicit cross-references to language objects, such as setq, 
cdaddr and zhstring-pluralize. 

• You can click on explicit cross-references, such as, see the section "String Con- 
version". 



Searching with the Show Candidates Command 

The Show Candidates command is your first choice for browsing through the docu- 
mentation database. While Show Candidates is fundamentally an index-search com- 
mand, it has several capacities beyond what is normally found in index-searching. 

• In the first place, Show Candidates searches through all the topic names in the 
database, and also searches through all the keywords (which are similar to index 
entries) as well. 

• Secondly, by default, Show Candidates performs "smart" (heuristic) searching. 
This means that you no longer have to think about the form of the word to sup- 
ply as a lookup request; the heuristic approach finds singulars and plurals, 
gerunds, negations, and so on. This is because the search is based on the stem 
of your lookup request. 

For example: The stem of "move" is "mov". Show Candidates move will match 
any topic names and keywords containing "move", "moves", "moved", "moving", 
*move-mumble*, ":move", and so on. (This is a hypothetical example. In fact 
*move-mumble* is not documented.) 

If you supply two or more words to Show Candidates, it searches for candidates 
that match all stems in any order. Thus, if you supply both "pathname" and "com- 
pletion" to Show Candidates, your candidates list includes both fsrcomplete- 
pathname and "Pathname Completion is Supported". This is the default behavior. 

You can specify adjacent search and also string searching by exact match, initial 
string, and substring by typing in your search term or terms and then pressing 
n-COMPLETE to display a menu from which you can choose those options. Press END 
to accept the choices displayed in boldface or RBORT to abort. 

If you select adjacent search and supply "pathname" and "completion" in that or- 
der, your candidates list will include only "Pathname Completion is Supported". 

Use the same menu to limit your search to exact matching, initial substring 
matching, and substring matching. 



Putting Topics Aside for Future Reading 

Occasionally in browsing through the database you notice topic names that look in- 
teresting but that you cannot or do not want to read immediately. Suppose, for ex- 
ample, that you are scrolling through several hundred current candidates generat- 
ed by the Show Candidates command. Rather than read the documentation for each 
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interesting topic as you come across it, you prefer to scan all the candidates first, 
mark all those topics that look like they might be helpful, and read them all at 
once later. Remembering their topic names would be extremely tedious. 

Document Examiner lets you put documentation aside for future reading by allow- 
ing you to explicitly insert a bookmark, or pointer, for a documentation topic. The 
topic name is added to the bookmarks pane. To insert a bookmark click sh-Middle 
on a mouse-sensitive topic name. 

Bookmarks are automatically inserted in two cases: whenever you read the docu- 
mentation for a topic into a viewer and when you look up documentation in a Lisp 
Listener or in the editor. In the latter case, the bookmarked is inserted in a spe- 
cial viewer called the Background viewer, but the topic is not displayed there. 

Bookmarks are used to create your own document for online viewing, see the sec- 
tion "Creating a Private Document". 

Particular bookmarks are associated with a particular viewer, so that when you se- 
lect another viewer, the list of bookmarks associated with it is also selected. 



Getting Information About a Documentation Topic 

Two commands — Show Overview and Show Table of Contents — are useful for 
examining the organization of topics within a document and for learning the posi- 
tion of a particular topic in the book or books in which it appears. 

Show Overview 

Sometimes you notice an intriguing-looking topic name among a list of current 
candidates but are not quite sure that the topic is the one you need. Before you 
commit yourself to reading it into the viewer, you might want to see how the topic 
fits into the structure of the book or books in which it appears or which other 
topics, related to it, are covered in the same book. Other times you might read a 
topic into the viewer and find that it is not quite at the right level of abstraction: 
it provides too much reference information, whereas you need more general cover- 
age. 

Document Examiner provides a command — Show Overview — that displays the 
position of a topic within the document or documents in which it appears. Given a 
topic, the command displays a two-part overview of the topic in a dynamic typeout 
window: 

The top part includes: 

• The type (is it a section of text or does it document a Lisp object, like a func- 
tion, for instance) and the name of the topic 

• Possibly a short summary of the topic 

• The names of any other topics in the documentation that include this one 
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• The names of any printed books that contain the topic 

• The topic's keywords (similar to index entries) 

• The names of related topics (cross-references) 

The names of topics and books in this display are mouse-sensitive. 

The bottom part is a graph of the document hierarchy around the topic you 
choose. (If the topic appears in more than than one document — multiple graphs 
are displayed.) This graph includes: 

• The topic that includes the original topic 

• Other topics included by the topic that includes the original topic 

• The topics the original topic includes 

Figure 52shows the display produced by doing Show Overview of the topic "Disk 

Error Handling". 

All the items in the overview graph are mouse-sensitive. 

For example, when you get an overview of "Disk Error Handling", you can see that 
the topic is included in the topic "Disk System User Interface" and that it includes 
four other topics. If this overview does not give you enough information, try an 
overview on the parent topic (in this case, "Disk System User Interface"). 

While the Show Candidates command searches through the entire documentation 
database, Show Overview helps you find out where you are in a document and how 
to navigate your way through it. 

Show Overview differs significantly from "Show Table Of Contents" . Compare the 
display of the two commands. See Figure 53. 

You can also find the printed book in which the topic appears by using the m-K 
What Document command in the editor. It displays the name of the printed book 
that contains the given documentation topic. If the topic is included in more than 
one book, the titles of all the books containing the given topic are listed. 

Show Table Of Contents 

Much as with printed documentation, you might want to become familiar with the 
overall structure of an online document before reading about any one topic. When 
you examine documentation online, the more general the topic you look up, the 
larger the amount of documentation you see for it. The most general topic names, 
obviously, are the names of the books in the printed documentation set. For exam- 
ple, if you asked to see the documentation for the topic name "Genera User's 
Guide", Document Examiner would display the contents of the entire book. This 
might not be what you want! 

The Show Table of Contents command is useful on those occasions: 
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Overview 

Section: "Disk Error Handling" 

It is included in topic: "Disk System User Interface" 

It appears in document: Internals 

Keywords: 

si: disk event suppress error recovery function 
grouping related disk transfers 
si: disk event error type function 



Disk System Definitions and 
/Constants 

/Disk Arrays 

/Disk Events 

vDisk Transfers 

-Disk Error Handling 



|3 Disk System User Interface^ 

1 



FEP File System and Disk 
Streams 

^■Disk Performance 

^Examples of High Disk 
Performance 

\TJisk and FEP File System 
Utilities 



Disk Error Conditions 
Disk Error Codes 
Disk Error Meters 



Figure 68. Document Examiner display of Show Overview of topic "Disk Error 
Handling". 



Document Examiner 



Section: "Lists" 

t is included in topic: "Data Types" 
t appears in document: Symbolics Common Lispr Language Concept* 

Lists 




v»t Candidates 



ling Information Rbout L 



Figure 69. The candidates pane shows the table of contents for a topic; the type- 
out window shows the overview of the same topic. 

• When you are unsure what level in the documentation you need (chapter level 
or section level, for example) 



• When you would like to become familiar with the organization of a document 
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Given a documentation topic name, the command displays the topic name and all 
the topic names subordinate to it in the candidates pane. For example, Figure 54 
shows the first pane of the table of contents of the document "Genera User's 
Guide". 



U 



Current Candidates 

Genera User's Guide 
H Overview of Symbolics Computers 

Documentation Notation Conventions 
Introduction to Genera 
The Console 
The Screen 
The Keyboard 
The Mouse 

The Mouse and Menus 
Mouse-sensitivity 
Scrol 1 i ng 
Menus 

System Menu 

lectins and Creating Windows 
Introduction: Selecting and Creating Wi 
Default Windows 
Movi ng 
SELECT Key 
ng Up 
ring Up 
Booting Rfter Powering up 

□ — in9 in ^ 



Se 



Starti 
Powe 
Cold 
Logg 



Figure 70. The candidates pane displays the table of contents for an entire docu- 
ment. 

The indentation of the candidates indicates the hierarchy of topics. 

You can ask to see a table of contents for any topic, not just a book. Of course, if 
a topic doesn't contain any other topics, then it has no table of contents. 

This command is also available in the editor as n-K Show Table of Contents. c-U 
n -K Show Table of Contents prints the table of contents on a printer. 

For more general searching, see the section "Searching with the Show Candidates 
Command". 



Site Configuration: A Conceptual Overview 

Site configuration enables your Symbolics computers to describe and access the re- 
sources available to them. Once your site has been configured, all of its Symbolics 
computers can find out about the other hosts, printers, and users there. 

Namespace service is at the heart of site configuration. In order for one machine 
(a local host) to use any of the resources provided by other machines (remote 
hosts), namespace service — managed and provided by a namespace server — is 
required. 
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A local host depends on the namespace server for answers to these questions: 

• How is the remote host connected to the local host (what is the remote host's 
network address)? 

• What network protocol must be used to obtain the desired service? 

By configuring your site, you give each Symbolics machine sufficient information 
to know where and how to obtain namespace service. You also give your name- 
space server sufficient information to provide that service. 

More information is available about the terms we use when discussing site config- 
uration. See the section "Glossary of Terms for Site Configuration". 



Site Configuration and Namespace Service 

The namespace server uses namespace files to describe each resource at a particu- 
lar site. The namespace server might not store the namespace files locally, but it 
knows where to locate them. 

If your site is large, with many (over ten) user machines to make demands on the 
namespace server, Symbolics recommends that you create a dedicated namespace 
server; use one Symbolics machine that's unavailable for user applications. If your 
site is small (under ten user machines), designate one of the user machines as the 
namespace server. 

The namespace server's purpose is to collect and maintain information for a site. 
All of the information known about a site's network(s) and each host, printer, and 
user is stored in the namespace database. More information is available about 
namespace objects and the namespace system. See the section "Setting Up and 
Maintaining the Namespace Database". 

There can be more than one namespace server at a site. One server is the primary 
namespace server; the others are secondary namespace servers. More information 
is available about the differences between server machines. See the section "Ma- 
chines and Worlds". 

A typical Symbolics site uses a namespace server to store the namespace database, 
and a file server to store system sources and online documentation. It is possible 
for one machine to perform both these services, provided it has enough disk space. 

There are some restrictions pertaining to servers. The namespace server must be a 
Symbolics computer. The system sources and online documentation must reside on 
one of the following: 

• A Symbolics computer. 

• Any UNIX host running NFS, in a . set directory (see the section "Using SCT 
with a UNIX File System") . 
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More information is available about system sources and online documentation. See 
the section "System Sources and Online Documentation". 



Choosing a Site Name 

As part of the site configuration process, you'll select a site name that designates 
the physical locale of your machines. (This is different from a host name. Host 
names designate particular machines at a given location.) 

When you are ready to configure your site, choose a site name that — in all prob- 
ability — will not be duplicated by another site. For example, if you are setting up 
a site at ACE Computers in Nutley, New Jersey, and your department works on 
robotics, you might call your site ACE-Robotics or ACE-Nutley rather than just 
ACE. 

Note: You cannot use a dot [.] as part of the site name that you choose. 



Choosing Machine Names and Network Addresses 

It is easier to refer to a computer by its name than by its Chaosnet (the Symbolics 
network) or Internet address. It is possible to refer to a host by its Chaosnet ad- 
dress, but this can become tedious. 

Most customers choose a theme by which to name their machines. For example, 
each Symbolics computer at your site might be named after different mountains, 
or famous scientists. 

Most sites have all of their machines on the same Ethernet cable. When you cre- 
ate a site, you select a subnet number for this cable. You also select a unique 
number for each machine. If you have machines on more than one Ethernet cable, 
you select a unique number for each cable. 

If you use networks such as NFS, DNA or IP-TCP along with Chaosnet, we sug- 
gest that when you configure your site, you employ an addressing scheme that will 
encompass all of these. More information is available about network addressing 
schemes, see the section "Network Addressing". 

Note: XL-family, 3600-family, UX-family and Maclvory machines come from Sym- 
bolics with Chaosnet address 52525. This is almost never what you want. In fact, 
if a site already has one machine using that address, the new one will be confused 
with the old one. NXP1000 machines come pre-configured with the Internet ad- 
dress that you specify at the time of purchase. If you did not specify one, you must 
boot your machine by hand when you install it, see the section "Caveats About 
NXP Installation". 



Format of Chaosnet Addresses 

A Chaos address is a 16-bit quantity, in which the high-order 8 bits represent the 
subnet number, and the low-order 8 bits represent the host number on that sub- 
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net. Neither the subnet number nor the host number can be zero. Chaos addresses 
are expressed in octal. 

Example: Chaos Address 401 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 

+ + + + + + + + + + + + + + + + + 

|0|0|0|0|0|0|0|1|0|0|0|0|0|0|0|1| 
+ + + + + + + + + + + + + + + + + 

|< Subnet number >|< Host number >| 

The subnet number is 1. 

The host number is 1. 

The Chaos address is 401 octal. 

For technical details on how the Chaosnet address is used: See the section "Chaos- 
net Addresses and Indices". 

Chaosnet addresses are displayed in octal, and each Chaosnet address at a site 
must be unique. For example, if you have a machine whose cable (subnet) number 
is 1 and whose machine (host) number is 2, the resulting Chaosnet address is 402. 

The lowest Chaosnet address that you can have is 401. Symbolics suggests that you 
use this number (401) as the Chaosnet address for your first machine, and that 
you number subsequent machines in ascending order. 

Format of Internet Addresses 

Internet addresses are expressed in decimal, in four octets separated by periods. 
Each octet is 8 bits long. There are three kinds of Internet addresses: Class A, 
Class B, and Class C. 

Examples of Internet addresses: 

• 10.2.0.7 is host 2.0.7 on Class A network 10. 

• 139.41.0.3 is host 0.3 on Class B network 139.41. 

• 192.10.0.200 is host 200 on Class C network 192.10.0. 

Note that the host number cannot be zero or 255, because those are considered 
broadcast addresses. 
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Interpreting Internet Addresses 

Internet addresses consist of network and host fields. The network field identifies 
the network, and the host field identifies the host on that network. This size of 
the Internet address depends on the address and the configuration of the network. 

You can use a subnet field for networks containing subnets. Using a subnet field 
divides the address into three fields. A subnet mask determines the bits used for 
selecting a subnet. Note that the rules for determining a subnet field vary for 
each network. 

Note: You cannot fill a field (network, subnet, or host field) with all zeros or ones 
for representing a network, subnet, or host. 

Class A Addresses 

A Class A Internet address is a 32-bit number, in which the high-order octet (8- 
bits) represents the network number and the following three octets represent the 
host number. The first octet is less than 128. 

Example of Class A Internet Address: 10.2.0.7 

1 00001 01 1 0000001 1 00000000 1 000001 1 1 | 
|<-net — >|< host >| 



Class B Addresses 

A Class B Internet address is a 32-bit number, in which the two high-order octets 
represent the network number and the following two octets represent the host 
number. The first octet of a Class B network is greater than or equal to 128 and 
less than 192. 

Example of Class B Internet Address: 139.41.0.3 

110001011 100101001 100000000100000011 | 
|< network >|< host >| 



Class C Addresses 

A Class C Internet address is a 32-bit number, in which the three high-order 
octets represent the network number and the low-order octet represents the host 
number. The first octet of a Class C network is greater than or equal to 192, and 
less than 224. 
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Example of Class C Internet Address: 192.10.0.200 

1 11000000 1 00001010 1 00000000 1 11001000 I 
|< network >|<-host->| 



Internet Subnet Number 

The Internet subnet number is the Internet address resulting from replacing the 
host field of an Internet address with zeros. You can determine the Internet sub- 
net number of a network by determining the class of a host address and replacing 
the host portion of the address with zeros. For example, the class B address 
128.81.38.232 corresponds to the Internet Subnet number 128.81.0.0. 

Subnet Masks 

A subnet mask determines the field of the Internet address specifying the subnet 
on the network. A subnet mask is a 32-bit quantity containing one in every bit cor- 
responding to the official Internet subnet number. Additionally, the subnet mask 
contains a zero in every bit selecting a host on a subnet. For example, A class B 
network (128.81.0.0) is broken into many subnets, using the third octet of the ad- 
dress for selecting a subnet. The Class B default mask is 255.255.0.0; since the 
third octet determines a subnet, you have to fill it with ones. The resulting subnet 
mask is 255.255.255.0. 



Mapping an Internet Address into a Chaos Address 

Once you have an Internet address for a host, you can map that address into a 
Chaos address. You can then assign sequential Chaos addresses for all Chaos hosts 
on the network. If you are on the Internet, you can use each host's Internet ad- 
dress to derive a Chaos address. 

The mapping process is best explained by example. The following two examples 
show the mapping of a Class B and Class C Internet address into a Chaosnet ad- 
dress: 



Class C Internet address: 192.10.41.48 decimal. 

Step 1: Get the Chaos subnet number and host number. 

192.10.41.48 is the Internet address. 

192 is unused in the mapping. 

10 is unused in the mapping. 

41 is the Chaos subnet number. 

48 is the Chaos host number. 
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Step 2: Convert the decimal subnet and host numbers to octal. 

The subnet number (41 decimal is 51 octal .) 
The host number (48 decimal is 60 octal .) 

Step 3: Insert subnet and host numbers into two eight-bit bytes. 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 

+ + + + + + + + + + + + + + + + + 

|0|0|1|0|1|0|0|1|0|0|1|1|0|0|0|0| 
+ + + + + + + + + + + + + + + + + 

|< Subnet number >|< Host number >| 

Step 4: Express the quantity in octal notation; this is the Chaos 
address. 

010 100 100 110 000 (binary representation) 
2 4 4 6 (octal representation) 

The resulting Chaos address is 24460 octal. 



Class B Internet address: 139.41.9.3 decimal. 

The subnet number is 9 decimal. 
The host number is 3 decimal. 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 

+ + + + + + + + + + + + + + + + + 

|0|0|0|0|1|0|0|1|0|0|0|0|0|0|1|1| 
+ + + + + + + + + + + + + + + + + 

|< Subnet number >|< Host number >| 

The resulting Chaos address is 4403 octal. 



Logical Pathnames and the SYS Host 

A logical pathname is one that does not correspond to any particular physical file 
system on a host. Logical pathnames make it easy to keep software on more than 
one type of file system. 
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For example, the set of files containing the Symbolics system sources and online 
documentation system is stored at each site. Some sites store these files on a Lisp 
Machine File System (LMFS), others store them on a VAX/Berkeley UNIX host 
with the Chaosnet package, and still others use a UNIX host running NFS in a 
.set directory (see the section "Using SCT with a UNIX File System"). It is also 
possible to use a VAX/VMS file server running DNA. More information is available 
about using VAX hosts. See the section "Site Configuration and Namespace 
Service". 

Symbolics software uses logical pathnames. All sites create a logical host (called 
SYS). Logical pathnames and the logical SYS host allow software to work correctly 
(and the same way) at every site. All pathnames for system software files are logi- 
cal, and all begin with the logical host SYS. Only the translation of each logical 
pathname to a physical pathname differs at each site. 

The translation of logical to physical pathnames depends on the translations files 
loaded into the current world. For more information about the translations files, 
see the section "Pathname Translation". 

A site that stores the system software on a UNIX system translates logical path- 
names into UNIX pathnames. A site that stores the system software on a LMFS 
translates logical pathnames into LMFS pathnames. 

The flexibility of logical pathnames enables sites to split their logical SYS host 
across several physical hosts. A given physical host might contain some of the sys- 
tem software, but the logical entity called a SYS host contains all of it. 



Machines and Worlds 

When you configure your site, you set up different machines to perform specific 
functions. Each type of machine (user, server, or namespace server) requires a dif- 
ferent kind of "world". 

User machines 

User machines may or may not have special software loaded into their worlds. The 
distinguishing characteristic of user machines is that they rely on other machines 
for specific services, such as file service (including access to the online documen- 
tation), printer service, and mail delivery. 

You can build special worlds for user machines if you want them to run special 
software (software that is not part of the distribution world). For example, you 
may load Symbolics non-loaded systems such as Conversion-Tools or Metering into 
the worlds that you run on the user machines. 

Server Machines 

Server machines are those machines designated to provide network services to 
many — or all — of the machines at a site. Typically, server machines provide the 
following services: 
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• File storage: They have a large file system (the LMFS) where many users store 
files. 

• Print spooling: They receive requests to hardcopy information, queue the infor- 
mation, and print it on one or more printers. 

• Store-and-Forward Mail Service: They receive mail messages and store them lo- 
cally in mail files for users, or forward them over the network. 

Any machine can offer these services. However, Symbolics recommends that a ma- 
chine upon which many (more than ten) user machines depend for services be used 
only as a server, and not also as a user machine. 

Often, servers run software that is not part of the distribution world. In particu- 
lar, the Print and Mailer systems have to be loaded in order to provide printer and 
store and forward mail services, respectively. 

To avoid loading these systems every time a server is booted — and to improve 
the server's performance — you will want to save separate server Incremental 
Disk Save (IDS) Worlds. You can then Optimize and Save the server worlds that 
contain whatever non-standard software systems your servers run. 

For information about IDS Worlds, the Optimize World command, and the Save 
World command, see the section "Making, Distributing, and Using Worlds". 

Namespace Servers 

Primary namespace servers read and write the permanent files of the namespace 
database. These files can be stored on any file server on the network. However, 
namespace update operations will run much faster if you store the namespace files 
on the primary namespace server's local LMFS. (This is only possible if the ma- 
chine has enough disk space to store the files.) 

Secondary servers are not namespace authorities, but they can serve as backups in 
case the primary server is temporarily unavailable. These servers attempt to keep 
a copy of the namespace information current by querying the primary server more 
often than a non-server machine would. 

Since namespace servers load namespace changes into virtual memory at boot 
time, booting on a namespace server will take progressively longer as your name- 
space grows. 

To save time, Symbolics recommends that you periodically create updated name- 
space server worlds. If you boot your most current site-configured world on a 
namespace server, all of the newest namespace information will (automatically) be 
loaded. When you save the newly booted world, you'll get a permanent copy of the 
up-to-date namespace information. 

Remember that each namespace server loads the namespace information only about 
(and for) those machines that it serves. If you have multiple namespace servers — 
and they serve different namespaces — you'll need to boot and save a different, 
updated world on each. 
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The Distribution World 

Core software, containing the Lisp language and all of the programming tools in- 
cluding the Zmacs editor, the Lisp Machine File System, the Zmail electronic mail 
facility, Document Examiner and others, is contained within the distribution world. 
This world is formally known as some version of Genera. 

When you receive a distribution world from Symbolics, it is without any cus- 
tomizations. Once you have loaded the distribution world onto a machine, you can 
make modifications to it (such as loading special systems or software) to customize 
it for your site. More information is available about customizing worlds for user, 
server, and namespace server machines. See the section "Machines and Worlds". 



Non-Loaded Systems 

Systems are collections of files that — when loaded together — affect the Lisp en- 
vironment in useful ways. For example, if you load the Print system into the Lisp 
environment of your machine, your machine will then have the capabilities of a 
print spooler. It will take hardcopy requests from other hosts and print them, one 
at a time, on a local printer. 

Some systems come already loaded into your world by Symbolics; these loaded sys- 
tems make up what is called the distribution (or base) world. Document Examiner 
is an example of a system that comes to you as part of the distribution world. 

Other systems aren't pre-loaded into the distribution world. These non-loaded sys- 
tems provide additional facilities that might only be needed by some Symbolics 
computers. An example of a non-loaded system is the Store-and-Forward Mailer. 

Most systems that Symbolics ships contain several files, and optionally include 
some patches. The patches are modifications that are too small to warrant compil- 
ing the entire system. 

Each system has a major and minor version number. The major version number 
indicates how many revisions and recompilations the system has had. The minor 
version number indicates how many patches were made to the system since the 
last revision or recompilation was made to it. 

More information is available about loading systems. See the section "Load System 
Command". 



System Sources and Online Documentation 

Symbolics distributes a portion of the sources from which the Genera environment 
was developed, including all of the documentation database. 

If you set up one or more machine(s) as server(s) for these files, then you have ac- 
cess to a portion of the system sources. This greatly enhances your development 
environment and facilitates your development of applications. 

You can access the Genera sources from anywhere on the network, without using 
any disk space other than that on the server machine. For more information: See 
the section "Logical Pathnames and the SYS Host". 
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In the Genera environment, all of the printed documentation is available online. 
You need only to select the Symbolics online documentation system, called Docu- 
ment Examiner, or to execute a few simple commands, in order to view any part of 
the documentation for the system. 

To use Document Examiner, press SELECT D. You can get a list of Document Ex- 
aminer commands by clicking Left on Help. You can get a list of topics to look up 
by using the Show Candidates command with several words of the general subject 
you want to find. You can display documentation by using the Show Documentation 
command on a known topic name or by clicking Left on a topic name in the candi- 
dates pane. 



Pruning the Documentation Database 

The documentation database consists of many files in a large directory on a file 
server. At some sites, file server space is limited and not all of the documentation 
files can be kept online. If this is the case at your site, you can selectively remove 
some of the documentation while still leaving users with online access to common- 
ly used documentation. 

Pruning affects only the file space used on the documentation server; it does not 
affect the part of the document database that resides in the worlds on individual 
machines. Document Examiner commands (such as Show Candidates and Show 
Overview) still find the names of sections that are in documents whose files have 
been deleted. 

When a user tries to look up a topic from a removed book, Document Examiner 
displays a notice that the topic appears in a book that has been removed from the 
online set. (The notice shows the book name and the name of the file that contains 
that particular section.) 

If users request it, you can restore files from tape to the documentation directory. 
The material in those files will be available for lookup as soon as they have been 
restored. 



Documentation Database Directories 

The directory SYS:DOC;iNSTALLED-N; contains the set of directories that hold the doc- 
umentation files. Because of the hypertext nature of our documentation, there is 
not a complete correspondance between a given set of files and a book (some files 
may contain records for more than one book, or some records may be used by sev- 
eral books). However, as a rough cut to help prune the documentation files, here is 
a list of the directories as they relate, for the most part, to particular books. This 
should allow you to remove the directories for those books that you do not use. 
Simply use Dired in Zmacs or the Command Processor command Delete Directory 
to delete the directories for those books you want to remove. Note: When using 
the Delete Directory command be sure that the pathname you specify is a directo- 
ry, not a file in a directory. In the latter case, the directory one level up is the 
one that gets deleted. See the section "Delete Directory Command". 



Page 742 



Books 1, 2, 3, and 4: 








Genera Concepts 








Genera Workbook 








Genera User's Guide 








Genera Handbook 










cp; 


hard; 


1ms; 




miscf; 


miscu; 


miscui 




nota; 


sage; 


user; 



Book 5: 

Editing and Mail 



conv; fed; zmacs; 

zmailc; zmailt; 



Book 6: 

Program Development Tutorial 



clyde; tools; workstyles; 



Books 7, 8, and 9: 






Symbolics Common Lisp - 






Language Concepts 






Programming Constructs 






Dictionary 








ansi-cl; arr; 


char; 




clcp; clos; 


cond; 




conversion-tools; data-types; 


defs; 




dictionary; eval; 


flav; 




flow; func; 


io; 




mac; miscf; 


pkg; 




prim; scope; 


strings; 




str; 





Books 10 and 11: 
Programming the User Interface 
User Interface Dictionary 



ined; menus; 
uims; scroll; 



new-uims; 
windoc; 



Book 12: 

Program Development Utilities 



comp; debug; maint; 

meter; meter-int; misct; 



Page 743 



Book 13: 
Networks 



netio; nfile; prot; 



Book 14: 








Internals 










audio; 


fep; 


instr; 




init; 


int; 


iprim; 




proc; 


sched; 


stor; 




tape; 







Site Administration 



fep; file; fsed; 
pig; site; 



Ivory Documentation: 



ivory; macivory; rpc; 
ux400; x!400; 



Installation Guides: 



sig; 



Genera 8.0 Release Notes 



rn8-0; 



Setting and Defining Sites 

This section describes the criteria for using the Set Site and Define Site Com- 
mands, and shows the Set and Define Site dialogues. See the section "Set Site 
Command". 

See the section "Define Site Command". 

Here are the criteria for determining whether to use the Set Site or Define Site 
command on a Symbolics 3600-family or Ivory-based machine: 



Set Site 



Define Site 



If the namespace files have already been created, use the Set 
Site comand. This gives your machine access to the already 
configured site's resources. 

If the namespace files do not yet exist, use the Define Site 
command. This creates a new namespace that you can expand 
later to include other hosts, sites, users, printers, and net- 
works. 
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Set Site Dialogue 

Issue the Set Site command. If you accept the default ("Get from network"), your 
machine broadcasts a query to other network machines to learn their site name 
and the identity of the local machine. 

Command: Set Site (site name [default Get from network])RETURN 

If you wish to change your site, or if information about your site is unavailable, 
enter a site name manually. In the examples that follow, Downunder is the name 
of a sample site. 

1. When the local host is the namespace server for your site: 

Connand: Set Site (site nane [default Get fron network]) doununder 

Paraneters for site DOWNUNDER 

Nanespace Nane: Doununder 

Nanespace Server Nane: Local 

Nanespace Descriptor File: HRTCH : >sys>si te>doununder-nanespace . text 

< abort > aborts^ <1S1> uses these values 

Figure 71. Local host is the namespace server 

If the name of the namespace server provided is "Local" or the name of the 
local host, the menu adjusts to ask for the name of the namespace descriptor 
file, since you are saying that the local host is the primary namespace server 
for the site, as in Figure 71 . 

2. If the name of the namespace server is different from the local host's name, 
the menu adjusts to ask for the network address of the Primary Namespace 
Server, as in Figure 56 . 

Connand: Set Site (site nane [default Get fron network]) doununder 

Paraneters for site DOWNUNDER 

Nanespace Nane: Doununder 

Nanespace Server Nane: Wonbat 

Nanespace Server Rddress: a pair of a network and an address 

< abort > aborts^ <1S1> uses these values 



Figure 72. Namespace server is not the local host 

The network must be a primary network for the local machine. The address 
must be a valid address for the network. Figure 57 shows the complete dialog 
for setting the site when the Primary Namespace Server is not the local host: 
These are all the parameters needed for setting site when the local host is 
not the primary namespace server. Of course, you could just say Set Site with 
no parameters, since the same server specified explicitly in this last example 
would presumably respond to the broadcast request from the local host. 
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Connand: Set Site (site nane [default Get fron network]) doununder 

Paraneters for site DOWNUNDER 

Nanespace Nane: Doununder 

Nanespace Server Nane: Wonbat 

Nanespace Server Rddress: CHROS 12345 

< abort > aborts^ <1S1> uses these values 



Figure 73. Complete menu for setting the site when the Primary Namespace 
Server is not the local host. 



4. When the local host is the primary namespace server, some additional param- 
eters may be necessary. Figure 58 shows the dialog when the local host is the 
Primary Namespace Server. The defaults are set up for the local LMFS. 

Connand: Set Site (site nane [default Get fron network]) doununder 

Paraneters for site DOWNUNDER 

Nanespace Nane: Doununder 

Nanespace Server Nane: Local 

Nanespace Descriptor File: HATCH : >sys>si te>dounundei — nanespace . te*t 

<rbort:> abortSj < E ™ D > uses these values 



Figure 74. Additional parameters needed when the local host is the Primary 
Namespace Server 



If the user provides a name for the local host that is not the current name or 
"Local". The address of the server will be requested. If the address is that of 
the local machine, the menu looks like this: 

Connand: Set Site (site nane [default Get fron network]) Doununder 

Paraneters for site DOWNUNDER 

Nanespace Nane: Doununder 

Nanespace Server Nane: Wonbat 

Nanespace Server Rddress: CHROS 24503 

Nanespace Descriptor File: HRTCH : >sys>si te>doununder-nanespace . text 

< abort > aborts^ <1S1> uses these values 

5. If the descriptor file is not on the local host, the minimal parameters neces- 
sary to access the host holding the descriptor file will be required. Note: Due 
to a bug, descriptor files cannot be stored on UNIX hosts. 

See the section "Customizing and Saving Worlds". 
Define Site Dialogue 
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In a Lisp Listener, issue the Define Site command and give a site name. This 
might be the name of your company, or it can be related to the machine names 
you have chosen. 

Command: Define Site (site name) Downunder 
A menu comes up with with the necessary fields to be filled in, as in Figure 61 : 

Connand: Define Site (site nane) Doununder 

Defining site DOWNUNDER with the local host as the Primary Nanespace Server 

Nanespace Server Nane: the nsne of the prinsry ns.nesps.ce server 

< abort > aborts^ <1S1> uses these values 



Figure 75. The basic Define Site menu 



Enter the name of your namespace server. The Define Site dialogue expects an ac- 
tual name here, so do not enter Local for the Namespace Server name. 

After you have entered the name of your namespace server, additional menu slots 
are displayed, with the appropriate default information filled in. You can, of 
course, change them. 

Connand: Define Site (site nane) doununder 

Defining site DOWNUNDER with the local host as the Prinary Nanespace Server 

Nanespace Server Nane: uonbat 

Systen File Directory: uonbat : >sys>si te> 

Nanespace Descriptor File: uonbat : >sys>si te>DOWNUNDER-nanespace . text 

Default Login: Lisp-Machine 

Host for Bug Reports: uonbat 

Local Tinezone: EDT 

Standalone Site: Yes No 

< abort > aborts^ <1S1> uses these values 



Figure 76. An expanded Define Site menu 



Namespace Server Name 

The name of the local host in the new site. 

System File Directory 

The physical directory that will correspond to the logical direc- 
tory SYS:SiTE; in the new site. For more information, see the 
section "Logical Pathnames and the SYS Host". 

Namespace Descriptor File 

The name of the file that will hold the namespace description 
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that is used to find all the files that make up the namespace 
database. 

Default Login The "Lispm name" of the user object "Lisp-Machine". 

Host for Bug Reports 

The name of the host that will accept bug-report mail. For in- 
formation about the mailer, see the section "Installing and 
Configuring the Mailer". 

Local Timezone The abbreviation of the local timezone or an integer indicating 
the hour offset from GMT. For more information about time 
zones, see the section "Specifying a Time Zone for Your Site". 

Standalone Site Whether the local site consists of just the local machine or 
not. A broadcast is used to verify the identity of the local host 
and get the current time when booting at non-standalone sites. 
Saying "Yes" means that these broadcasts will not be per- 
formed. 

Press END to define your site. 

If a name other than the Namespace Server Name is used in the Namespace De- 
scriptor File, System File Directory, or Host for Bug Reports fields, the dialog will 
ask for additional parameters to define these hosts in the new site. This informa- 
tion consists of system-types, addresses, and file protocols used to access files on 
the hosts. 

You are now ready to log in and use the newly configured software. The local host 
is automatically registered at the newly defined site. You may want to save the 
new, site-specific version of your world. For more information, see the section 
"Customizing and Saving Worlds". 



Specifying a Time Zone for Your Site 

All sites are in some time zone. The time zone translates user-specified time into 
universal time. Users specify their site's time zone by modifying the time zone at- 
tribute of their site object. This can be done during the Define Site dialogue 
and/or with the Namespace Editor. 

When you boot a distribution world, if the machine is unable to get the time from 
the network and does not trust its calendar clock (typically because the FEP has 
been reset, or the board has been replaced, or the machine is new) you are first 
prompted for a local time zone and then for the local time. 

It is possible to set your time zone with mnemonic symbols. Besides Eastern Stan- 
dard Time (EST), Central Standard Time (CST), and Pacific Standard Time (PST), 
you can use other commonly accepted mnemonics for time zones for all over the 
world. You can specify a time zone as an offset from Greenwich Mean Time 
(GMT) as well as by mnemonic name. 



Page 748 



Specify time zones west of GMT by their mnemonic if one is defined, or by a four- 
digit number preceded by a - (for west of GMT) or a + (for east of GMT). Four- 
digit numbers must be in the range -1200 to 1200 and can end either in 00 or 30. 

For example, -0500 means five hours west of Greenwich, and is equivalent to EST. 
It is also possible to allow time zones on the half hour, like South Australian Stan- 
dard time, which is 9.5 hours east of GMT. You specify this by either SAST or 
+0930. See the function timertimezone-string. 



Daylight Savings Time 

Every area of the world has its own rules that control when daylight savings time 
is in effect. The system "knows about" daylight savings time for time zones in the 
United States (but not for European countries or other time zones). 

If you are in a time zone outside of the United States, you must manually tell the 
system when daylight savings time is in effect. Do this by using the Namespace 
Editor to edit your site object. 

Edit your site object with the Edit Namespace Object command, using a name- 
space class of Site. Use the mouse to replace the time zone with a new one of 
your choice. 

Note: When you create a site, you are queried for a time zone (this happens dur- 
ing the Define Site dialogue). If your site is in the United States, enter the stan- 
dard version of your local time zone (like EST), regardless of whether daylight 
savings is in effect. If you enter your time zone using the Namespace Editor, enter 
just the standard time zone as well. 

Here is a complete list of the time zones that adjust automatically during daylight 
savings: 



Time Zone 


Abbreviation 


Atlantic Standard Time 


AST 


Central Standard Time 


CST 


Eastern Standard Time 


EST 


Mountain Standard Time 


MST 


Pacific Standard Time 


PST 


Yukon Standard Time 


YST 


Alaska-Hawaii Standard Time 


AHST 


Hawaii Standard Time 


HST 


Time Zone 


Abbreviation for Daylight Savings 


Atlantic Standard Time 


ADT 


Eastern Standard Time 


EDT 


Central Standard Time 


CDT 


Mountain Standard Time 


MDT 


Pacific Standard Time 


PDT 


Yukon Standard Time 


YDT 


Alaska-Hawaii Standard Time 


AHDT 
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New Zealand Daylight Time NZD 

Glossary of Terms for Site Configuration 

This section defines some terms related to site configuration. 

namespace Every site has a namespace associated with it. The namespace 

is a database in which names of users, hosts, and printers are 
resolved into their representative objects. (See namespace 
database, below.) 

namespace server A namespace server maintains the namespace database files 
(see namespace, above). A namespace server also processes 
queries and updates about the mappings and the objects to 
which those mappings refer. All hosts chosen as namespace 
servers must be Symbolics computers. 

primary namespace server 

A namespace has a single primary namespace server. This serv- 
er is responsible for maintaining the files that make up the 
namespace database, and for controlling the access of users 
and secondary namespace servers to this information. 

secondary namespace server 

A namespace can have one or more secondary namespace 
servers. These servers answer queries when their information 
is up-to-date, and they can ask the primary server for up-to- 
date information. Secondary namespace servers are most useful 
for large sites (more than 25 machines). 

namespace database The namespace database consists of a number of files contain- 
ing information about objects of various classes. You can cre- 
ate, modify, or delete objects in the namespace database by us- 
ing the Namespace Editor. 

To run the Namespace Editor, click on [Namespace Editor] in 
the System menu or use the Edit Namespace Object command. 
The namespace database usually resides in files located in the 
SYS:SITE; logical directory. 

The default location for the namespace database is on the pri- 
mary namespace server. The default name for the file that con- 
tains the names of the other files making up the database (the 
namespace description file) is as follows (where SITENAME is 
the registered name of the site): 

>sys>site>SITENAME-namespace.text 

Other files constituting the database would have names such 
as: 
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>sys>site>SITENAME-namespace-log.text 

>sys>site>SITENAME-namespace-changes.text 

>sys>site>SITENAME-hosts.text 

>sys>site>SITENAME-users.text 

>sys>site>SITENAME-objects.text 

The Edit Namespace Object command can be run on any host 
at the site. To update a database, both the primary namespace 
server and the host on which the namespace database resides 
must be available. 

objects and classes The namespace database contains objects. Objects can fall with- 
in different classes. The set of classes in the namespace 
database is as follows: 

namespace 

site 

host 

user 

network 

printer 

For example, suppose you have a user, CHARLIE, logged in to 
Symbolics machine TUNA at site FISHERY. The user, host, 
and site are all registered in the namespace called FISHERY. 

• FISHERY is an object of class namespace (because it's the 
name of the namespace that contains the site FISHERY, the 
user CHARLIE, and the host TUNA). 

• FISHERY (a second object) is a object of class site (because 
it's also the name of the site). 

• TUNA is a host object. 



namespace object 



standalone site 



• CHARLIE is a user object. 

A namespace object is a resource (a namespace, site, host, user, 
network, or printer) that's registered in a namespace database. 

The most common standalone site is a single Symbolics ma- 
chine that is not connected to any network. However, because 
only Symbolics machines can provide namespace service, a site 
is also considered standalone if it consists of one Symbolics 
machine and any number of non-Symbolics-machine hosts. 

An organization with several Symbolics machines, none of 
which is on a network, constitutes several independent stand- 
alone sites; that is, each machine appears as the single Sym- 
bolics machine host at a standalone site. 
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who-am-i The who-am-i request is part of the procedure Symbolics ma- 

chines use at boot time to determine if the saved Lisp environ- 
ment matches the current site. 



